league / config
Define configuration arrays with strict schemas and access values with dot notation
Fund package maintenance!
colinodell
www.colinodell.com/sponsor
www.paypal.me/colinpodell/10.00
Installs: 179 893 487
Dependents: 24
Suggesters: 0
Security: 0
Stars: 497
Watchers: 7
Forks: 14
Open Issues: 3
Requires
- php: ^7.4 || ^8.0
- dflydev/dot-access-data: ^3.0.1
- nette/schema: ^1.2
Requires (Dev)
- phpstan/phpstan: ^1.8.2
- phpunit/phpunit: ^9.5.5
- scrutinizer/ocular: ^1.8.1
- unleashedtech/php-coding-standard: ^3.1
- vimeo/psalm: ^4.7.3
This package is auto-updated.
Last update: 2024-12-11 00:17:33 UTC
README
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.
📦 Installation
This project requires PHP 7.4 or higher. To install it via Composer simply run:
composer require league/config
🧰️ Basic Usage
The Configuration
class provides everything you need to define the configuration structure and fetch values:
use League\Config\Configuration; use Nette\Schema\Expect; // Define your configuration schema $config = new Configuration([ 'database' => Expect::structure([ 'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(), 'host' => Expect::string()->default('localhost'), 'port' => Expect::int()->min(1)->max(65535), 'ssl' => Expect::bool(), 'database' => Expect::string()->required(), 'username' => Expect::string()->required(), 'password' => Expect::string()->nullable(), ]), 'logging' => Expect::structure([ 'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true), 'file' => Expect::string()->deprecated("use logging.path instead"), 'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(), ]), ]); // Set the values, either all at once with `merge()`: $config->merge([ 'database' => [ 'driver' => 'mysql', 'port' => 3306, 'database' => 'mydb', 'username' => 'user', 'password' => 'secret', ], ]); // Or one-at-a-time with `set()`: $config->set('logging.path', '/var/log/myapp.log'); // You can now retrieve those values with `get()`. // Validation and defaults will be applied for you automatically $config->get('database'); // Fetches the entire "database" section as an array $config->get('database.driver'); // Fetch a specific nested value with dot notation $config->get('database/driver'); // Fetch a specific nested value with slash notation $config->get('database.host'); // Returns the default value "localhost" $config->get('logging.path'); // Guaranteed to be writeable thanks to the assertion in the schema // If validation fails an `InvalidConfigurationException` will be thrown: $config->set('database.driver', 'mongodb'); $config->get('database.driver'); // InvalidConfigurationException // Attempting to fetch a non-existent key will result in an `InvalidConfigurationException` $config->get('foo.bar'); // You could avoid this by checking whether that item exists: $config->exists('foo.bar'); // Returns `false`
📓 Documentation
Full documentation can be found at config.thephpleague.com.
💭 Philosophy
This library aims to provide a simple yet opinionated approach to configuration with the following goals:
- The configuration should operate on arrays with nested values which are easily accessible
- The configuration structure should be defined with strict schemas defining the overall structure, allowed types, and allowed values
- Schemas should be defined using a simple, fluent interface
- You should be able to add and combine schemas but never modify existing ones
- Both the configuration values and the schema should be defined and managed with PHP code
- Schemas should be immutable; they should never change once they are set
- Configuration values should never define or influence the schemas
As a result, this library will likely never support features like:
- Loading and/or exporting configuration values or schemas using YAML, XML, or other files
- Parsing configuration values from a command line or other user interface
- Dynamically changing the schema, allowed values, or default values based on other configuration values
If you need that functionality you should check out other libraries like:
- symfony/config
- symfony/options-resolver
- hassankhan/config
- consolidation/config
- laminas/laminas-config
🏷️ Versioning
SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase.
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.
🛠️ Maintenance & Support
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.
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.
(This policy may change in the future and exceptions may be made on a case-by-case basis.)
👷️ Contributing
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.
🧪 Testing
composer test
📄 License
league/config is licensed under the BSD-3 license. See the LICENSE.md
file for more details.
🗺️ Who Uses It?
This project is used by league/commonmark.