Laravel Persistent Configuration Repository

This extension introduces persistent configuration repository for Laravel. Its usage in particular provides support for application runtime configuration, loading config from database.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the require section of your composer.json.

Usage

This extension allows reconfiguration of already created config repository using data from the external storage like relational database. It provides special config repository class \Illuminatech\Config\PersistentRepository, which wraps any given config repository, adding a layer for saving and restoring of data from the persistent storage.

Config data, which should be saved in persistent storage defined via \Illuminatech\Config\PersistentRepository::setItems(). Only keys, which are explicitly defined as "items", will be stored or retrieved from the persistent storage. Any other data present in the source config repository will remain as it is.

PersistentRepository fully decorates any config repository, matching \Illuminate\Contracts\Config\Repository and can substitute \Illuminate\Config\Repository instance. In particular this allows you to substitute regular Laravel config by \Illuminatech\Config\PersistentRepository instance, applying configuration from database to the entire application. You can do so in your AppServiceProvider class. For example:

Then anytime you access 'config' service in your application via config() function, \Illuminate\Support\Facades\Config facade or via service container you will interact with \Illuminatech\Config\PersistentRepository instance getting values modified by database data.

Tip: with this extension there is no need for manually putting any data into actual storage (e.g. writing DB migrations or Seeding) - it will be filled up automatically. If value for the particular item is missing in the storage, it will be simply picked up from the wrapped config repository (e.g. as defined at 'config/*.php' files). However, some storages require some preparations before they can function, like creating a database table.

Note: this extension does not provide built in service provider for application config substitute as it might be not desired for particular application, while \Illuminatech\Config\PersistentRepository usage is not limited with this task. However, you can use \Illuminatech\Config\Providers\AbstractPersistentConfigServiceProvider class as a scaffold for such service provider. For example:

Do not forget to register your particular persistent config service provider in "providers" section at "config/app.php":

You may also manage persistent configuration per particular application entity. For example: imagine we need to allow application user to customize appearance of his profile page, like changing color schema or enable/disable sidebar and so on. Such settings can be managed by \Illuminatech\Config\PersistentRepository bound to the user Eloquent model. Such model class may look like following:

It will allow you to operate persistent configuration per each user record separately, so profile page composition may look like following:

Configuration items specification

Config parts, which should be saved in the persistent storage are defined by \Illuminatech\Config\PersistentRepository::setItems(), which accepts a list of \Illuminatech\Config\Item or configuration array for it. Each configuration item should define a key, which leads to the target value in source repository. Configuration item also has several properties, which supports creation of web interface for configuration setup. These are:

• 'id' - string, item unique ID in the list, this value will be used in request fields and form inputs.
• 'label' - string, verbose label for the config value input.
• 'hint' - string, verbose description for the config value or input hint.
• 'rules' - array, value validation rules.
• 'cast' - string, native type for the value to be cast to.
• 'encrypt' - bool, whether to encrypt value for the storage or not.
• 'options' - array, additional descriptive options for the item, which can be used as you see fit.

Since only 'key' is mandatory item may be specified by single string defining this key.

Here are some examples of item specifications:

Configuration storage

Declared configuration items may be saved into persistent storage and then retrieved from it. The actual item storage can be any class matching \Illuminatech\Config\StorageContract interface.

Following storages are available within this extension:

• \Illuminatech\Config\StorageDb - stores configuration inside relational database;
• \Illuminatech\Config\StorageEloquent - stores configuration using Eloquent models;
• \Illuminatech\Config\StoragePhp - stores configuration in local PHP files;
• \Illuminatech\Config\StorageArray - stores configuration in runtime memory;

Please refer to the particular storage class for more details.

Saving and restoring data

\Illuminatech\Config\PersistentRepository will automatically retrieve config item values from persistent storage on the first attempt to get config value from it.

You may also manually fetch data from persistent storage using restore() method:

Heads up! Any error or exception, which appears during values restoration, will be automatically suppressed. This is done to avoid application blocking in case storage is not yet ready for usage, for example: database table does not yet exist. Storage failure error will appear only at the application log. You should manually test value restoration is working at your application to avoid unexpected behavior.

To save config data into persistent storage use method save():

Changes made via regular config repository interface (e.g. via methods set(), push() and so on) will not be automatically saved into the persistent storage. However, you may use synchronize() method to save current config item values into it.

Tip: You may invoke synchronize() at the application terminating stage ensuring all changes made during application running are saved.

Method reset() clears all data saved to the persistent storage, restoring original (e.g. default) config repository values.

You can also use resetValue() method to reset particular config key only.

Caching

You can use PSR-16 compatible cache storage to improve performance of the config item retrieval from persistent storage. For example:

Validation

Each configuration item comes with validation rules, which matches ['sometimes' ,'required'] by default. You can easily create a validation for the user input before config saving, using these rules, or use \Illuminatech\Config\PersistentRepository::validate(). For example:

You can also use \Illuminatech\Config\PersistentRepository::makeValidator() method to create a validator instance for manual processing.

Heads up! Watch for usage dot symbols ('.') inside the input in case you do not use \Illuminatech\Config\PersistentRepository::validate() method. By default Laravel considers dots in validation rules as array nested keys separator. You should either prefix them with backslash ('\') or manually define \Illuminatech\Config\Item::$id in the way it does not contain a dot.

Creating configuration web interface

One of the most common use case for this extension is creating a web interface, which allows control of application configuration in runtime. \Illuminatech\Config\PersistentRepository serves not only for applying of the configuration - it also helps to create an interface for configuration editing.

The web controller for configuration management may look like following:

You can operate \Illuminatech\Config\Item interface during HTML form input composition. For example:

Tip: you can use \Illuminatech\Config\Item::$options to setup configuration for the dynamic form inputs, specifying input type, CSS class and so on inside of it.

Heads up! Remember that PHP automatically replaces non-alphanumeric characters like dot ('.'), dash ('-') and so on inside request keys during native 'POST' parsing, making collection and validation for keys like 'config.some-key' impossible. You will need to setup \Illuminatech\Config\Item::$id value for each persistent configuration item manually, in case you going to submit values via regular 'POST' request. For example:

Tip: you will not face this problem in case you submit configuration item values via REST API interface using JSON format or via native (not spoofed) 'PUT' request.

In case you are using Laravel Nova for your application admin panel, you can easily create an application configuration setup interface with illuminatech/nova-config extension.

Typecast

You may operate complex type values like arrays as a persistent ones. In order to do so, you should specify config item typecasting via \Illuminatech\Config\Item::$cast. For example:

Encryption

In case you are planning to operate sensitive data like passwords, API keys and so on, you may want to store them as an encrypted strings rather than the plain ones. This can be achieved enabling \Illuminatech\Config\Item::$encrypt. For example:

Note that data encryption will impact the config repository performance.

Garbage collection

As your project evolves new configuration items may appear as well as some becomes redundant. \Illuminatech\Config\PersistentRepository automatically ignores any value in persistent storage in case it has no matching config item set by setItems(). Thus stored obsolete values will not affect config repository anyway, however they still may consume extra space inside the storage. You may manually remove all obsolete values from the storage, using gc() method:

In case Illuminatech\Config\PersistentRepository::$gcEnabled enabled garbage collection will be performed automatically each time config values are saved via save() or synchronize() method.