Introduction
Cartalyst's Composite Config package enhances illuminate/config
to allow configuration items to be placed within a database whilst cascading back to the filesystem.
This is super useful for building user interfaces that facilitate editing configuration for an app. Because it does not change the API for retrieving configuration items, it degrades gracefully to the filesystem if not present and requires zero changes to the places which use the configuration items.
The package follows the FIG standard PSR-0 to ensure a high level of
interoperability between shared PHP code and is fully unit-tested.
Getting started
The package requires at least PHP version 5.3.
Have a read through the Installation Guide.
Quick Example
// Set config at runtime
Config::set($key, $value);
// Set persisting config at runtime
Config::getLoader()->set($key, $value);
Installation
The best way to install the Composite Config package is quickly and easily done with Composer.
Open your composer.json
and add the following to the require
array
"cartalyst/composite-config": "1.1.*"
Add the following lines after the require
array on your composer.json
file
"repositories": [
{
"type": "composer",
"url": "https://packages.cartalyst.com"
}
]
Note: Make sure your
composer.json
file is in a valid JSON format after the required changes.
Install the dependencies
Run Composer to install or update the new requirement.
php composer install
or
php composer update
Now you are able to require the vendor/autoload.php
file to PSR-0 autoload the library.
Example
// Include the composer autoload file
require_once 'vendor/autoload.php';
// Import the necessary classes
use Cartalyst\CompositeConfig\CompositeLoader;
use Illuminate\Config\Repository;
use Illuminate\Database\Connection;
use Illuminate\Filesystem\Filesystem;
// Setup config loader
$loader = new CompositeLoader(new Filesystem(), '/path/to/config/files');
// Attach the optional database loading functionality.
// Without this, the composite loader acts like the default file loader.
$database = new Connection(new PDO('mysql:dbname=my_database;host=127.0.0.1'), $prefix = '');
$loader->setDatabase($database);
// Instantiate config
$config = new Repository($loader);
// Set persisting config
$config->getLoader()->set($key, $value);
Integration
Laravel 4
The Composite Config package has optional support for Laravel 4 and it comes bundled with a
Service Provider for easier integration.
After you have installed the package correctly, just follow the instructions.
Open your Laravel config file app/config/app.php
and add the following lines.
In the $providers
array add the following service provider for this package.
'Cartalyst\CompositeConfig\CompositeConfigServiceProvider',
Migrations
In order to run the migration successfully, you need to have a default database connection setup on your Laravel 4 application, once you have that setup, you can run the following command:
php artisan migrate --package=cartalyst/composite-config
Configuration
After installing, you can publish the package's configuration file into your
application by running the following command:
php artisan config:publish cartalyst/composite-config
This will publish the config file to app/config/packages/cartalyst/composite-config/config.php
where you can modify the package configuration.
Usage
Retrieving Config
Usage is identical to that explained in the Laravel documentation
Config::get($key);
Saving Config
There are two ways of saving configuration items.
1. Runtime
To set configuration at runtime, use
Config::set($key, $value);
During that request, calling Config::get($key);
will return the value you have set.
Note: Configuration values that are set at run-time are only set for the current request, and will not be carried over to subsequent requests.
2. Persisting
To set persisting configuration at runtime, use
Config::getLoader()->set($key, $value);
Note: When persisting a config item, the value will be (by default) persisted for the current environment only.
Ex. if you're running in the 'local' environment and switch to 'production', your item won't load.
Overcoming this is easy, just provide '*' as the third parameter -Config::getLoader()->set($key, $value, '*');
and it will work for all environments.
Cascading
Below is the order in which items are cascaded:
- Database configuration for the current environment
- Database configuration for all environments (persisted by providing '*' as the third parameter)
- Filesystem configuration for the current environment
- Filesystem configuration for all environmentts
Any number of these may be absent, it will be skipped.
Limitations
In Laravel 4, configuration is used to resolve database credentials as well as a number of core options. Because of this, any config items requested before the composite config package is loaded will be cached. Typically, this is just the config within app/config/app.php
and app/config/database.php
and app/config/session.php
. There is a way around this if you require to override these config items:
Config::set('*::app', null);
Config::set('*::database', null);
Config::set('*::session', null);
This will remove these items from the cache and force them to be re-fetched from the database. Be sure to inject the new values into anywhere they've been previously injected.
Note: Most people shouldn't need to worry about the above.