README

A PHP configuration management library that supports file-based storage and loads each section lazily.

Features

• Section-Based Configuration: Organize your config into named sections for better structure and readability.
• ArrayAccess & Magic Methods: Access configuration sections and keys using array syntax or object properties.
• Lazy Loading of Sections: Configuration sections are loaded only when accessed, reducing memory usage and improving performance.
• Type-Safe Access: Supports IDE autocomplete and type hinting via Proxy classes and PHPDoc annotations.
• Dot Notation Support: Easily get or set nested configuration values with intuitive dot paths (e.g., database.connections.mysql.host).
• Defaults Handling: Define default values for keys, ensuring fallback values when a key is missing.
• File-Based Persistence: Save and load configuration sections to individual PHP files.
• Dynamic Proxy System: Each configuration section is accessible via a Proxy class, providing seamless interaction and encapsulation.
• Caching: Optional APCu or file-based caching to improve performance by storing available file metadata.
• Utility Methods: Easily manage keys, delete sections, iterate over values, or eject sections from memory.

Installation

Install via Composer:

composer require nabeghe/configurator

Usage

1. Create a configuration class and extend it from Configurator.
2. Define the DEFAULTS constant in this class. This constant is an array that can contain arbitrary values. Each key represents a section, and its value is an array of that section’s configuration values (for example: db, log, etc.).
3. It is recommended to create a separate class for each section. This class is used only for IDE type hinting and has no other functional purpose. In this class, you can define the keys that the section may contain, along with their types, using @property annotations in the docblock comments. This class must extend the Proxy class, because each section is a Proxy.
4. Instantiate your configuration class.

Configurator Constructor

The constructor accepts three parameters:

• First parameter: The path to a directory where each section can be stored as a separate PHP file. Each file must return an array. For example, a section named db.php can be used for database configuration. The default value is null, meaning no directory is used.
• Second parameter: Configuration data. You may inject configuration data for each section at instantiation time. In this case, the data will not be loaded from the directory. The default value is an empty array.
• Third parameter: Specifies whether APCu should be used. It is used only to cache the list of available files and has no other purpose. If not set, a file named _.cache will be used in the specified directory instead.

Note 1:
By default, the directory path is null. If it is not set, loading configuration from files and persisting configurations is not possible. Therefore, if your configuration is file-based, you should set this path.

Note 2:
Injecting data together with a directory path is allowed. In this case, the injected sections will no longer be loaded from their corresponding files.

use Nabeghe\Configurator\Configurator;
use Nabeghe\Configurator\Proxy;

class MyConfig extends Configurator
{
    const DEFAULTS = [
        'db' => [
            'type' => 'mysql',
            'host' => 'localhost',
            'port' => 3306,
        ],
        'debug' => [
            'enabled' => true,
        ],
    ];
}

$config = new MyConfig(path: __DIR__ . '/config');

// Accessing sections via Proxy
$db = $config->db;
echo $db->host; // localhost

// Using dot notation
$config->dot('db.host', '127.0.0.1');
echo $config->dot('db.host'); // 127.0.0.1

// Adding new keys or editing
$config->app->version = '1.0.0';

// Save a section
$config->db->save();

// Delete a key
$config->db->del('port');

// Iterate through keys
$config->database->each(function($key, $value) {
    echo "$key => $value\n";
});

// Get all configuration data including defaults
$allConfig = $config->getAll(addDefaults: true);

Cache file

A file named _.cache is reserved. If APCu is not available, the list of existing configuration files is stored in this file. Although the system automatically updates the list, it is recommended to delete the _.cache file whenever you add a new file or remove an existing one.

Configurator class

Proxy class

This class is used for each configuration section.

📖 License

Licensed under the MIT license, see LICENSE.md for details.