CodeIgniter Settings

https://github.com/codeigniter4/settings
Admin
This project provides database storage and retrieval of application settings, with a fallback to the...
Tokens:13,485
Snippets:123
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### FileHandler configuration example

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Example configuration array for the FileHandler, specifying class, path, writeable, and deferWrites options.

```php
public $file = [
    'class'        => FileHandler::class,
    'path'         => WRITEPATH . 'settings',
    'writeable'    => true,
    'deferWrites'  => false,
];
```

--------------------------------

### Install CodeIgniter Settings with Composer

Source: https://github.com/codeigniter4/settings/blob/develop/README.md

Install the CodeIgniter Settings package via Composer.

```bash
composer require codeigniter4/settings
```

--------------------------------

### Manual Installation: Autoload Configuration

Source: https://github.com/codeigniter4/settings/blob/develop/docs/installation.md

Add the CodeIgniter\Settings namespace to the $psr4 array in app/Config/Autoload.php for manual installation.

```php
<?php

// ...

public $psr4 = [
    APP_NAMESPACE => APPPATH, // For custom app namespace
    'Config'      => APPPATH . 'Config',
    'CodeIgniter\Settings' => APPPATH . 'ThirdParty/settings/src',
];

// ...
```

--------------------------------

### Deferred writes example

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Example showing multiple set() calls with deferWrites false and true, illustrating the difference in file writes.

```php
// With deferWrites = false: 1 file read (hydrates all settings for class) + 3 separate file writes
$settings->set('Example.prop1', 'value1');
$settings->set('Example.prop2', 'value2');
$settings->set('Example.prop3', 'value3');

// With deferWrites = true: 1 file read + 1 file write (all changes batched at end of request)
```

--------------------------------

### Using the setting() helper

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Loads the setting helper and demonstrates the shorthand functions for getting, setting, and forgetting settings. The helper must be loaded with helper('setting') before use. Note that the helper cannot access contextual settings.

```php
helper('setting');

$name = setting('App.siteName');
// Store a value
setting('App.siteName', 'My Great Site');

// Using the service through the helper
$name = setting()->get('App.siteName');
$settings = setting()->getMany([
    'App.siteName',
    'App.siteEmail',
]);
setting()->set('App.siteName', 'My Great Site');
setting()->setMany([
    'App.siteName'  => 'My Great Site',
    'App.siteEmail' => 'support@example.com',
]);

// Forgetting a value
setting()->forget('App.siteName');
setting()->forgetMany([
    'App.siteName',
    'App.siteEmail',
]);
```

--------------------------------

### DatabaseHandler configuration example

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Example configuration array for the DatabaseHandler. The 'class' key must be set to DatabaseHandler::class. The 'table' option defaults to 'settings', 'group' to null (default connection), 'writeable' to true, and 'deferWrites' to false. Requires running migrations with 'php spark migrate -n CodeIgniter\\Settings' to create the settings table.

```php
public $database = [
    'class'        => DatabaseHandler::class,
    'table'        => 'settings',
    'group'        => null,
    'writeable'    => true,
    'deferWrites'  => false,
];
```

--------------------------------

### Get a setting value with service('settings')->get()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/index.md

Retrieves the stored value for a config key. If the value has not been updated in the database, the original config file value is returned.

```php
service('settings')->get('App.siteName');
```

--------------------------------

### Get a config value with service('settings')->get()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Retrieves a single configuration value using the settings service with dot notation. The comment notes that this is equivalent to config('App')->siteName.

```php
// The same as config('App')->siteName;
$siteName = service('settings')->get('App.siteName');
```

--------------------------------

### Get a contextual value with get() or setting() helper

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Retrieves a contextual setting using the service or the setting() helper. Contexts cascade: if a context does not match, it falls back to the general value, then config value, then null.

```php
$context = 'user:' . user_id();
$theme = service('settings')->get('App.theme', $context);

// or using the helper
setting()->get('App.theme', $context);
```

--------------------------------

### Deferred writes example with set() calls

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Shows how multiple set() calls behave with deferWrites disabled (each call triggers separate queries) versus enabled (batched at end of request). The comment explains the query count difference: with deferWrites=false, 1 SELECT + 3 separate INSERT/UPDATE queries; with deferWrites=true, 1 SELECT + 1 INSERT batch + 1 UPDATE batch. This is useful for reducing database queries when updating many settings.

```php
// With deferWrites = false: 1 SELECT (hydrates all settings for context) + 3 separate INSERT/UPDATE queries
$settings->set('Example.prop1', 'value1');
$settings->set('Example.prop2', 'value2');
$settings->set('Example.prop3', 'value3');

// With deferWrites = true: 1 SELECT + 1 INSERT batch + 1 UPDATE batch (all batched at end of request)
```

--------------------------------

### Retrieve multiple values with getMany()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Retrieves multiple configuration values in one call. Returns an array keyed by the exact setting names requested, unlike get() which returns a single value.

```php
$settings = service('settings')->getMany([
    'App.siteName',
    'App.siteEmail',
]);
```

--------------------------------

### Batch operations with setMany()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Example of using setMany() to perform explicit batch updates. This is recommended for explicit batches when you need to update multiple settings at once, especially beneficial when updating existing records or performing many operations in a single request.

```php
$settings->setMany([
    'Example.prop1' => 'value1',
    'Example.prop2' => 'value2',
    'Example.prop3' => 'value3',
]);
```

--------------------------------

### Migrate Database for Settings

Source: https://github.com/codeigniter4/settings/blob/develop/README.md

Run database migrations for the Settings package.

```bash
php spark migrate --all
```

--------------------------------

### Publish settings config

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Run this command to publish the settings configuration file to app/Config/Settings.php for modifications.

```bash
php spark settings:publish
```

--------------------------------

### Set a setting value with service('settings')->set()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/index.md

Stores a value for a config key in the database. The key format is 'App.siteName' where 'App' is the config file and 'siteName' is the property. If not overridden, the config file value is used.

```php
service('settings')->set('App.siteName', 'Example');
```

--------------------------------

### Migrate Settings on Windows

Source: https://github.com/codeigniter4/settings/blob/develop/docs/installation.md

Run migrations only for the CodeIgniter\Settings namespace on Windows.

```console
php spark migrate -n CodeIgniter\Settings
```

--------------------------------

### Set handlers to file then database

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Configures the settings to check the file handler first, then the database handler. If neither has a value, the default value from the config file is returned.

```php
public $handlers = ['file', 'database'];
```

--------------------------------

### Migrate Settings on Unix

Source: https://github.com/codeigniter4/settings/blob/develop/docs/installation.md

Run migrations only for the CodeIgniter\Settings namespace on Unix systems.

```console
php spark migrate -n CodeIgniter\\Settings
```

--------------------------------

### Remove all settings with flush()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Immediately removes all settings from persistent storage and the in-memory cache.

```php
service('settings')->flush();
```

--------------------------------

### Forget a setting value with service('settings')->forget()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/index.md

Removes the stored value for a config key, reverting to the config file default.

```php
service('settings')->forget('App.siteName');
```

--------------------------------

### Set a contextual value with set() and context

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Sets a contextual setting using a context string. The context is passed as an additional parameter to set(); if a context setting does not exist, the general value is used.

```php
$context = 'user:' . user_id();
service('settings')->set('App.theme', 'dark', $context);
```

--------------------------------

### Save a value with set()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Saves a single configuration value. Note that boolean true/false are stored as strings ':true' and ':false' but converted back to booleans on retrieval; arrays and objects are serialized when saved and unserialized when retrieved.

```php
service('settings')->set('App.siteName', 'My Great Site');
```

--------------------------------

### Configure ArrayHandler in PHP

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Use this PHP array to configure the ArrayHandler with the class and writeable options. The class defaults to ArrayHandler::class and writeable defaults to true. Data is not persisted between requests.

```php
public $array = [
    'class'     => ArrayHandler::class,
    'writeable' => true,
];
```

--------------------------------

### Set handlers to database only

Source: https://github.com/codeigniter4/settings/blob/develop/docs/configuration.md

Configures the settings to use only the database handler. Handlers are checked in order, and the first one with a value returns it.

```php
public $handlers = ['database'];
```

--------------------------------

### Set multiple contextual values with setMany() and context

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Sets multiple contextual values in one call using setMany() with a context parameter.

```php
$context = 'user:' . user_id();
service('settings')->setMany([
    'App.theme' => 'dark',
    'App.locale' => 'en',
], $context);
```

--------------------------------

### Clear settings with spark settings:clear

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Clears all settings from the database using the spark command line tool. You will be prompted to confirm the action before it is performed.

```bash
php spark settings:clear
```

--------------------------------

### Save multiple values with setMany()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Saves multiple key/value pairs in one call. Behaves like calling set() for each pair but allows supported handlers to persist changes more efficiently.

```php
service('settings')->setMany([
    'App.siteName'  => 'My Great Site',
    'App.siteEmail' => 'support@example.com',
]);
```

--------------------------------

### Delete multiple values with forgetMany()

Source: https://github.com/codeigniter4/settings/blob/develop/docs/basic-usage.md

Deletes multiple values from persistent storage in one call.

```php
service('settings')->forgetMany([
    'App.siteName',
    'App.siteEmail',
]);
```
Tokens:
Raw