Cartalyst LLC.
Composite-config by Cartalyst
0
23
0
5
0

This package requires a valid subscription. Subscribe for access.

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:

  1. Database configuration for the current environment
  2. Database configuration for all environments (persisted by providing '*' as the third parameter)
  3. Filesystem configuration for the current environment
  4. 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.

You wont find fancy lifestyle graphics and marketing bravado here. Just cold... hard... code...

Code Well, Rock On!
Processing Payment...