Skip to content

Usage

Minimal config library with support for Array and JSON files.

Creation

Configs can be created specifically using new Config, new ArrayConfig or new JsonConfig. Configs can also automatically detect the file driver when using Config::from($file).

<?php
use Symbiont\Config\{Config, ArrayConfig, JsonConfig};

$config = new Config($options = []); // driverless by default
$config = new ArrayConfig($file, $options = []);
$config = new JsonConfig($file, $options = []);

$config = Config::from($file, $options = []);
// returns a driver based config.

Note

Only .php and .json supported for now.

Default config methods

By default, Symbiont\Config\Config is not configured with any driver. It can be used as a base class to implement any given config. Therefor it does not load, save or store any files.

Method Type
get(string $key) Get a value by key mixed
set(string $key, mixed $value) Set key/value self
unset(string $key) Remove value by key self
add(string $key, mixed $value) Add a value to an array self
remove(string $key) Remove a value from an array self
values() Get or set values array | self
Default setup
<?php
use Symbiont\Config\{Config, ArrayConfig, JsonConfig};

$config = new Config([ /* options */ ]);
// same with ..
// $config = new ArrayConfig;
// $config = new JsonConfig;
$config->values([
    'test' => 'testing,
    'multiple' => [
        'values'
    ]
]);

get()

<?php
$config->get('test');
// returns `testing`
$config->get('doesntexist', 'default-value');
// returns `default-value`
$config->get('multiple');
// returns `['values']`

set()

<?php
$config->set('some-key', 'some-value');
// sets key `some-key` with value `some-value`
$config->set('multiple', 'testing');
// overwrites array value

unset()

<?php
$config->unset('some-key');
// removes key `some-key`

add()

<?php
$config->add('multiple', 'added');
// adds value `added` to key `multiple`
// results in `['values', 'added']`

remove()

<?php
$config->remove('multiple', 'values');
// removes value `values` from
// key `multiple` results in `['added']`

values()

<?php
$config->values();
// without arguments returns the current state of the config object is returned
$config->values([
    'new' => 'setting'
]);
// sets new state of the config object (overwrite)

Xpath

Xpath delimiter

The default Config supports xpath like behaviour to navigate through an array. The default separator is ->, whereas the default can be changed using ConfigSettings::$xpath_delimiter globally or locally on the config object using Config->xpath_delimiter

<?php
use Symbiont\Config\Config;
use Symbiont\Config\ConfigSettings;

// locally per config object
$config = new Config;
$config->xpath_delimiter = '.';

// globally for all config objects
ConfigSettings::$xpath_delimiter = '.';

Using xpath with get/set/unset/add and remove

Get a value using xpath.

<?php
$config->values([
    'some' => [
        'nested' => [
            'value' => 'as a string'
        ]           
    ]
]);
$config->get('some->nested->value');
// returns `as a string`
$config->get('this->does->not->exist', 'default-value');
// returns `default-value`

$config->set('some->nested->value', 'new value');
$config->set('some->nested', [
    'new-key' => 'with-value'
]);
// sets a new value to `some->nested->value`.
$config->unset('some->nested->new-key');
// removes key `new-key` from array `some->nested`
$config->add('some->nested', [
    'value' => 'as a string'
]);
// adds key with value `as a string` to array `nested`.
$config->remove('some->nested', 'value');
// removes key value from array `nested`

Set values with xpath

<?php
use Symbiont\Support\Config;

$config = new Config;
$config->values([

]);

File based config Drivers

Type Driver
PHP Array Drivers\ArrayConfigDriver
JSON Drivers\JsonConfigDriver

Loading a configuration from file

The path to any file is by default relative to the projects root folder. Example project structure:

 - configs/
   - project.json
 - src/
   - SomeClass.php
 - tests/
   - unit/
   - bootstrap.php
 - vendor/
 - .gitignore

<?php
use Symbiont\Config\Config;

$config = Config::from('./configs/project.json');
// Creates a ArrayConfig object with `./configs/project.json` as its source.

PHP Array Configuration

PHP Array driver uses the .php file extension returning an array.

<?php
return [
    'some' => 'value'
];

JSON Configuration

JSON driver uses the .json file extension and PHP's native json extension compiled in PHP since version 8.0.0. 

{
  "some": "value"
}

Env configuration

Will be included in milestone v1.4 as a separate package.

YAML configuration

Will be included in milestone v1.4 as a separate package.

Custom file based driver

  • @todo

Database based config drivers

Type Driver
Mysql Drivers\MysqlDatabaseDrivers

Mysql

The MySQL based driver is a proof of concept to separate the complete logic of file driver based and database driver based. It's quite pointless to store configurations in the database unless its relationally relevant, e.g. user profile configurations.

Custom database based driver

  • @todo

Callbacks

Each driver incorporates a simple lightweight Dispatcher for callbacks. (See the DispatchesEvent trait)

Using the on() method, the following events will be triggered.

Event
loading Before the values gets loaded from source
loaded After values has been loaded from
saving Before saving to source
saved After saving to source
storing Before creating a new source
stored After the new source was created
unlinking Before removing the source
unlinked After the source has been removed

Events called at construction time of a config object (e.g. loading or loaded) can be assigned via the Config's constructor $options parameter (including all other events)

<?php

$config = new Config([
    'callbacks' => [
        'loading' => function($event) {
            // before the file was loaded
        }   
    ]
])

Force value types

Will be included in milestone v1.3

A lot of work to do ..