You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

153 lines
7.0 KiB

3 years ago
  1. # league/config
  2. [![Latest Version](https://img.shields.io/packagist/v/league/config.svg?style=flat-square)](https://packagist.org/packages/league/config)
  3. [![Total Downloads](https://img.shields.io/packagist/dt/league/config.svg?style=flat-square)](https://packagist.org/packages/league/config)
  4. [![Software License](https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square)](LICENSE)
  5. [![Build Status](https://img.shields.io/github/workflow/status/thephpleague/config/Tests/main.svg?style=flat-square)](https://github.com/thephpleague/config/actions?query=workflow%3ATests+branch%3Amain)
  6. [![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/thephpleague/config.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/config/code-structure)
  7. [![Quality Score](https://img.shields.io/scrutinizer/g/thephpleague/config.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/config)
  8. [![Sponsor development of this project](https://img.shields.io/badge/sponsor%20this%20package-%E2%9D%A4-ff69b4.svg?style=flat-square)](https://www.colinodell.com/sponsor)
  9. **league/config** helps you define nested configuration arrays with strict schemas and access configuration values with dot notation. It was created by [Colin O'Dell][@colinodell].
  10. ## 📦 Installation
  11. This project requires PHP 7.4 or higher. To install it via [Composer] simply run:
  12. ``` bash
  13. $ composer require league/config
  14. ```
  15. ## 🧰️ Basic Usage
  16. The `Configuration` class provides everything you need to define the configuration structure and fetch values:
  17. ```php
  18. use League\Config\Configuration;
  19. use Nette\Schema\Expect;
  20. // Define your configuration schema
  21. $config = new Configuration([
  22. 'database' => Expect::structure([
  23. 'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
  24. 'host' => Expect::string()->default('localhost'),
  25. 'port' => Expect::int()->min(1)->max(65535),
  26. 'ssl' => Expect::bool(),
  27. 'database' => Expect::string()->required(),
  28. 'username' => Expect::string()->required(),
  29. 'password' => Expect::string()->nullable(),
  30. ]),
  31. 'logging' => Expect::structure([
  32. 'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true),
  33. 'file' => Expect::string()->deprecated("use logging.path instead"),
  34. 'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(),
  35. ]),
  36. ]);
  37. // Set the values, either all at once with `merge()`:
  38. $config->merge([
  39. 'database' => [
  40. 'driver' => 'mysql',
  41. 'port' => 3306,
  42. 'database' => 'mydb',
  43. 'username' => 'user',
  44. 'password' => 'secret',
  45. ],
  46. ]);
  47. // Or one-at-a-time with `set()`:
  48. $config->set('logging.path', '/var/log/myapp.log');
  49. // You can now retrieve those values with `get()`.
  50. // Validation and defaults will be applied for you automatically
  51. $config->get('database'); // Fetches the entire "database" section as an array
  52. $config->get('database.driver'); // Fetch a specific nested value with dot notation
  53. $config->get('database/driver'); // Fetch a specific nested value with slash notation
  54. $config->get('database.host'); // Returns the default value "localhost"
  55. $config->get('logging.path'); // Guaranteed to be writeable thanks to the assertion in the schema
  56. // If validation fails an `InvalidConfigurationException` will be thrown:
  57. $config->set('database.driver', 'mongodb');
  58. $config->get('database.driver'); // InvalidConfigurationException
  59. // Attempting to fetch a non-existent key will result in an `InvalidConfigurationException`
  60. $config->get('foo.bar');
  61. // You could avoid this by checking whether that item exists:
  62. $config->exists('foo.bar'); // Returns `false`
  63. ```
  64. ## 📓 Documentation
  65. Full documentation can be found at [config.thephpleague.com][docs].
  66. ## 💭 Philosophy
  67. This library aims to provide a **simple yet opinionated** approach to configuration with the following goals:
  68. - The configuration should operate on **arrays with nested values** which are easily accessible
  69. - The configuration structure should be **defined with strict schemas** defining the overall structure, allowed types, and allowed values
  70. - Schemas should be defined using a **simple, fluent interface**
  71. - You should be able to **add and combine schemas but never modify existing ones**
  72. - Both the configuration values and the schema should be **defined and managed with PHP code**
  73. - Schemas should be **immutable**; they should never change once they are set
  74. - Configuration values should never define or influence the schemas
  75. As a result, this library will likely **never** support features like:
  76. - Loading and/or exporting configuration values or schemas using YAML, XML, or other files
  77. - Parsing configuration values from a command line or other user interface
  78. - Dynamically changing the schema, allowed values, or default values based on other configuration values
  79. If you need that functionality you should check out other libraries like:
  80. - [symfony/config]
  81. - [symfony/options-resolver]
  82. - [hassankhan/config]
  83. - [consolidation/config]
  84. - [laminas/laminas-config]
  85. ## 🏷️ Versioning
  86. [SemVer](http://semver.org/) is followed closely. Minor and patch releases should not introduce breaking changes to the codebase.
  87. Any classes or methods marked `@internal` are not intended for use outside this library and are subject to breaking changes at any time, so please avoid using them.
  88. ## 🛠️ Maintenance & Support
  89. When a new **minor** version (e.g. `1.0` -> `1.1`) is released, the previous one (`1.0`) will continue to receive security and critical bug fixes for *at least* 3 months.
  90. When a new **major** version is released (e.g. `1.1` -> `2.0`), the previous one (`1.1`) will receive critical bug fixes for *at least* 3 months and security updates for 6 months after that new release comes out.
  91. (This policy may change in the future and exceptions may be made on a case-by-case basis.)
  92. ## 👷‍️ Contributing
  93. Contributions to this library are **welcome**! We only ask that you adhere to our [contributor guidelines] and avoid making changes that conflict with our Philosophy above.
  94. ## 🧪 Testing
  95. ``` bash
  96. $ composer test
  97. ```
  98. ## 📄 License
  99. **league/config** is licensed under the BSD-3 license. See the [`LICENSE.md`][license] file for more details.
  100. ## 🗺️ Who Uses It?
  101. This project is used by [league/commonmark][league-commonmark].
  102. [docs]: https://config.thephpleague.com/
  103. [@colinodell]: https://www.twitter.com/colinodell
  104. [Composer]: https://getcomposer.org/
  105. [PHP League]: https://thephpleague.com
  106. [symfony/config]: https://symfony.com/doc/current/components/config.html
  107. [symfony/options-resolver]: https://symfony.com/doc/current/components/options_resolver.html
  108. [hassankhan/config]: https://github.com/hassankhan/config
  109. [consolidation/config]: https://github.com/consolidation/config
  110. [laminas/laminas-config]: https://docs.laminas.dev/laminas-config/
  111. [contributor guidelines]: https://github.com/thephpleague/config/blob/main/.github/CONTRIBUTING.md
  112. [license]: https://github.com/thephpleague/config/blob/main/LICENSE.md
  113. [league-commonmark]: https://commonmark.thephpleague.com