README

A Symfony 2.7+ bundle which allows you to store multiple project configuration settings using different backends for data storage.

安装

Add this bundle to your project as a composer dependency: simply add a dependency on bluesteel42/settings-bundle to your project's composer.json file. Here is a minimal example of a composer.json file that just defines a dependency on SettingsBundle

    {
        "require": {
            "bluesteel42/settings-bundle": "~1.0"
        }
    }

Add the bundle in your application kernel

// app/AppKernel.php
public function registerBundles()
{
    // ...
    $bundles[] = new BlueSteel42\SettingsBundle\BlueSteel42SettingsBundle();
}

后端配置

The SettingsBundle works out of the box without the needing of specific configuration, using the Yaml backend by default and storing data under %kernel.root_dir%/Resources directory. If you need to use a different backend just put it in your config.yml

bluesteel42_settings: xml

Valid backends are: yml, xml, doctrinedbal.

Yaml 和 XML 后端

yml and xml backends store data in a file. In order to change the default directory under which the file is stored you must use the extended configuration

bluesteel42_settings:
    backend: xml
        path: path/to/my/dir

Doctrine DBAL 后端

This backend stores data in a database table. By default it uses the bluesteel42_settings table and the Doctrine connection named default.
You can modify one or both these parameters with the extended configuration

bluesteel42_settings:
    backend: doctrinedbal
        connection: my_connection
        table: my_settings_table

The table can be created using the console command

bluesteel42_settings:install

Please see the command help for more information.

缓存配置

The SettingsBundle uses a cache to speed-up data loading and provides adapters for Memcached and file-based cache. A special Null adapter is also provided to let you disable the cache for debugging purposes. The Null adapter is enabled by default.

Each cache adapter has specific configuration options.

NullCache

Since this adapter is enabled by default the following configurations are equivalent

    bluesteel42_settings:
        cache: ~

    bluesteel42_settings:
        cache: 'null'

    bluesteel42_settings:
        cache:
            'null': true

This adapter does note have further configuration parameters.

基于文件的缓存

This adapter stores the cached data in a cache file placed by default under the %kernel.cache_dir%/bluesteel42_settings directory. This adapter can be enabled with its default configuration with the following keys in your config.yml

    bluesteel42_settings:
        cache: file

If you need to modify the default path under which the cache file is stored just the path key

    bluesteel42_settings:
        cache:
            file:
                path: 'path/to/my/cache/dir'

It is strongly recommended to keep the cache file somewhere under %kernel.cache_dir% in order to have it cleaned up every time you invoke a cache:clear console command.

Memcached

This adapter uses the php-memcached extension to store cached data under one or more memcached servers. Each server must be specified as in the following example

    bluesteel42_settings:
        cache:
            memcached:
                servers:
                    - { host: localhost, port: 11211 }
                    - { host: my_remote_cache_server, port: 11222 }

用法

The SettingsBundle exposes a bluesteel42.settings that acts as a settings repository.
Each setting value is identified by a key. You can use a dot (.) to create a key hierarchy.

获取值

Keys can be retrieved using the method get($key, $default = null)

//  Get the service
$service = $this->get('bluesteel42.settings');
//  Get a key
$value = $service->get('my_key');
// Get a subkey
$subValue = $service->get('second_key.sub_key.third_level_key');
// Get a key with a default value if not found
$items_per_page = $service->get('items_per_page', 10);

设置值

A key value can be set using the method set($key, $value).

//  Set a key
$service->set('items_per_page', 20);
//  Set a subkey
$service->set('my_key.sub_key','subval1');

If the value is an array, a subkey is created for each key of the array.

$myArray = array('first' => 'red', 'second' => 'blue', 'third' => 'yellow');
$service->set('colors', $myArray);
echo $service->get('colors.first'); // outputs 'red'

请注意，设置键时，无论是否存在子键，旧值将被覆盖。例如，按照上面的示例

$service->set('colors', 'black and white');
echo $service->get('colors.first'); // outputs null
echo $service->get('colors'); // outputs 'black and white'

删除值

可以使用方法 delete($key) 删除键。给定的键及其所有子键（如果有的话）都将被删除。

//  Delete a key
$service->delete('my_key');

持久化更改

每次更改都必须显式持久化。如果不这样做，更改将在执行结束时丢失。
可以通过调用方法 flush() 来持久化更改。

//  Flush Modification
$service->flush();

提示

单次调用获取或设置所有键

您可以使用方法 getAll() 在一个调用中检索所有键，并使用 setAll(array $values 设置所有键值。
请注意，由于使用子键定义了层次结构，方法 getAll() 返回一个多维数组，显然，方法 setAll() 需要一个多维数组来正确存储数据集。

$allValues = array('colors.first' => 'red', 'colors.second' => 'blue'); // wrong

//correct
$allValues = 
    array(
        'colors' => 
            array(
                'first' => 'red', 
                'second' => 'blue'
            )
    );
    
$service->setAll($allValues);

链式调用

方法 set($key, $value) 允许您进行链式调用

$service->set('controller.one', 1)
    ->set('controller.two', 2)
    ->set('controller.three', 3)
    ->set('controller.four', 4)
    ->flush();