update docs

Author: michalsn

docs/configuration.md

@@ -0,0 +1,118 @@
+# Configuration
+
+To make changes to the config file, you need to have your own copy in `app/Config/Settings.php`. The easiest way to do it is by using the publish command.
+
+When you run:
+
+    php spark settings:publish
+
+You will get your copy ready for modifications.
+
+---
+
+## Handlers
+
+An array of handler aliases to use for storing and retrieving settings. Handlers are checked in order, with the first handler that has a value returning it.
+
+**Type:** `array`
+
+**Default:** `['database']`
+
+**Available handlers:** `database`, `file`, `array`
+
+Example:
+
+```php
+public $handlers = ['database'];
+```
+### Multiple handlers
+
+When multiple handlers are configured, they are checked in the order specified in $handlers. The first handler that has a value for the requested setting will return it.
+
+Example with fallback:
+
+```php
+public $handlers = ['file', 'database'];
+```
+This configuration will:
+
+1. Check the file handler first
+2. If not found, check the database handler
+3. If not found in any handler, return the default value from the config file
+
+### Writeable Handlers
+
+Only handlers marked as `writeable => true` will be used when calling `set()`, `forget()`, or `flush()` methods.
+
+## DatabaseHandler
+
+This handler stores settings in a database table and is production-ready for high-traffic applications.
+
+**Available options:**
+
+* `class` - The handler class. Default: `DatabaseHandler::class`
+* `table` - The database table name for storing settings. Default: `'settings'`
+* `group` - The database connection group to use. Default: `null` (uses default connection)
+* `writeable` - Whether this handler supports write operations. Default: `true`
+
+Example:
+
+```php
+public $database = [
+    'class'     => DatabaseHandler::class,
+    'table'     => 'settings',
+    'group'     => null,
+    'writeable' => true,
+];
+```
+
+!!! note
+    You need to run migrations to create the settings table: `php spark migrate -n CodeIgniter\\Settings`
+
+---
+
+## FileHandler
+
+This handler stores settings as PHP files and is optimized for production use with built-in race condition protection.
+
+**Available options:**
+
+* `class` - The handler class. Default: `FileHandler::class`
+* `path` - The directory path where settings files are stored. Default: `WRITEPATH . 'settings'`
+* `writeable` - Whether this handler supports write operations. Default: `true`
+
+Example:
+
+```php
+public $file = [
+    'class'     => FileHandler::class,
+    'path'      => WRITEPATH . 'settings',
+    'writeable' => true,
+];
+```
+
+!!! note
+    The `FileHandler` automatically creates the directory if it doesn't exist and checks write permissions on instantiation.
+
+---
+
+## ArrayHandler
+
+This handler stores settings in memory only and is primarily useful for testing or as a parent class for other handlers.
+
+**Available options:**
+
+* `class` - The handler class. Default: `ArrayHandler::class`
+* `writeable` - Whether this handler supports write operations. Default: `true`
+
+Example:
+
+```php
+public $array = [
+    'class'     => ArrayHandler::class,
+    'writeable' => true,
+];
+```
+
+!!! note
+    `ArrayHandler` does not persist data between requests. It's mainly used for testing or extended by other handlers.

docs/limitations.md

@@ -2,8 +2,8 @@
 
 The following are known limitations of the library:
 
-1. You can currently only store a single setting at a time. While the `DatabaseHandler` uses a local cache to
-   keep performance as high as possible for reads, writes must be done one at a time.
+1. You can currently only store a single setting at a time. While the `DatabaseHandler` and `FileHandler`
+   uses a local cache to keep performance as high as possible for reads, writes must be done one at a time.
 2. You can only access the first level within a property directly. In most config classes this is a non-issue,
    since the properties are simple values. Some config files, like the `database` file, contain properties that
    are arrays.

mkdocs.yml

@@ -53,7 +53,7 @@ extra:
 site_url: https://settings.codeigniter.com/
 repo_url: https://github.com/codeigniter4/settings
 edit_uri: edit/develop/docs/
-copyright: Copyright © 2023 CodeIgniter Foundation.
+copyright: Copyright © 2025 CodeIgniter Foundation.
 
 markdown_extensions:
   - admonition
@@ -73,5 +73,6 @@ extra_javascript:
 nav:
   - Home: index.md
   - Installation: installation.md
+  - Configuration: configuration.md
   - Basic usage: basic-usage.md
   - Limitations: limitations.md