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

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