yaffs.net Git - yaffs-website/blob - vendor/dflydev/dot-access-configuration/README.md

   1 Dot Access Configuration
   2 ========================
   3
   4 Given a deep data structure representing a configuration, access
   5 configuration by dot notation.
   6
   7 This library combines [dflydev/dot-access-data](https://github.com/dflydev/dflydev-dot-access-data)
   8 and [dflydev/placeholder-resolver](https://github.com/dflydev/dflydev-placeholder-resolver)
   9 to provide a complete configuration solution.
  10
  11
  12 Requirements
  13 ------------
  14
  15  * PHP (5.3+)
  16  * [dflydev/dot-access-data](https://github.com/dflydev/dflydev-dot-access-data) (1.*)
  17  * [dflydev/placeholder-resolver](https://github.com/dflydev/dflydev-placeholder-resolver) (1.*)
  18  * [symfony/yaml](https://github.com/symfony/Yaml) (>2,<2.2) *(suggested)*
  19
  20
  21 Usage
  22 -----
  23
  24 Generally one will use an implementation of `ConfigurationBuilderInterface`
  25 to build `ConfigurationInterface` instances. For example, to build a Configuration
  26 out of a YAML file, one would use the `YamlFileConfigurationBuilder`:
  27
  28     use Dflydev\DotAccessConfiguration\YamlFileConfigurationBuilder;
  29
  30     $configurationBuilder = new YamlFileConfigurationBuilder('config/config.yml');
  31     $configuration = $configurationBuilder->build();
  32
  33
  34 Once created, the Configuration instance behaves similarly to a Data
  35 instance from [dflydev/dot-access-data](https://github.com/dflydev/dflydev-dot-access-data).
  36
  37     $configuration->set('a.b.c', 'ABC');
  38     $configuration->get('a.b.c');
  39     $configuration->set('a.b.e', array('A', 'B', 'C'));
  40     $configuration->append('a.b.e', 'D');
  41
  42
  43 Custom Configurations
  44 ---------------------
  45
  46 Configuration Builders use Configuration Factories and Placeholder Resolver
  47 Factories behind the scenes in order to build a working configuration.
  48
  49 Under normal circumstances one should not need to do anything with the
  50 Placeholder Resolver Factory. However, one may wish to extend the
  51 default `Configuration` class or use an entirely different implementation
  52 altogether.
  53
  54 In order to build instances of custom `ConfigurationInterface` implementations
  55 with the standard builders, one would need to implement
  56 `ConfigurationFactoryInterface` and inject it into any
  57 `ConfigurationBuilderInterface`.
  58
  59 If a Configuration is declared as follows:
  60
  61     namespace MyProject;
  62
  63     use Dflydev\DotAccessConfiguration\Configuration;
  64
  65     class MyConf extends Configuration
  66     {
  67         public function someSpecialMethod()
  68         {
  69             // Whatever you want here.
  70         }
  71     }
  72
  73 Create the following factory:
  74
  75     namespace MyProject;
  76
  77     use Dflydev\DotAccessConfiguration\ConfigurationFactoryInterface;
  78
  79     class MyConfFactory implements ConfigurationFactoryInterface
  80     {
  81         /**
  82          * {@inheritdocs}
  83          */
  84         public function create()
  85         {
  86             return new MyConf;
  87         }
  88     }
  89
  90 To use the factory with any builder, inject it as follows:
  91
  92     use Dflydev\DotAccessConfiguration\YamlFileConfigurationBuilder;
  93     use MyProject\MyConfFactory;
  94
  95     $configurationBuilder = new YamlFileConfigurationBuilder('config/config.yml');
  96
  97     // Inject your custom Configuration Factory
  98     $configurationBuilder->setConfigurationFactory(new MyConfFactory);
  99
 100     // Will now build instances of MyConfFactory instead of
 101     // the standard Configuration implementation.
 102     $configuration = $configurationBuilder->build();
 103
 104
 105 License
 106 -------
 107
 108 This library is licensed under the New BSD License - see the LICENSE file
 109 for details.
 110
 111
 112 Community
 113 ---------
 114
 115 If you have questions or want to help out, join us in the
 116 [#dflydev](irc://irc.freenode.net/#dflydev) channel on irc.freenode.net.