jasny / config
Configure your application
Requires
- php: >=7.1
- jasny/dotkey: ^1.0
- jasny/php-functions: ^3.3|^4.0
- psr/container: ^1.0
Requires (Dev)
- ext-json: *
- ext-mysqli: *
- ext-yaml: *
- aws/aws-sdk-php: ^3.2
- jasny/php-code-quality: 2.3.*
- nette/neon: ^2.3
- phpstan/phpstan: ^0.10.2
- phpstan/phpstan-strict-rules: ^0.10.1
- symfony/yaml: ^3.0
Suggests
- aws/aws-sdk-php: Required to load configuration from AWS DynamoDB
- nette/neon: Required to use the NEON notation
- symfony/yaml: To support YAML without the yaml php extension
README
Configure your application. Implements PSR-11 to be used as container.
Installation
Jasny Config is registred at packagist as jasny/config and can be easily installed using composer.
composer require jasny/config
Usage
use Jasny\Config; $config = (new Config()) ->load('settings.yml') ->load('settings.dev.yml', ['optional' => true]);
Loaders
- Dir
- Ini
- Json
- Yaml
- Symfony
- Yaml extension
- Env
- DynamoDB
The DelegateLoader
can pick a loader based on class name or file extension.
For every loader; a Jasny\Config\LoadException
is thrown if the loader can't load the settings.
Dir
DirLoader
loader will traverse through every file in a directory. It uses the filename (without extension) as key name.
option | type | default | |
---|---|---|---|
recursive | bool | false | Traverse recursively through subdirectories |
optional | bool | false | Return empty config is directory doesn't exist |
base_path | string | getcwd() | Basepath for relative paths |
Ini
IniLoader
parses an INI file using parse_ini_file
.
option | type | default | |
---|---|---|---|
process_sections | bool | false | Group settings by section name |
mode | enum | INI_SCANNER_NORMAL | Mode of parsing options (off = false, etc) |
optional | bool | false | Return empty config is file doesn't exist |
base_path | string | getcwd() | Basepath for relative paths |
Json
JsonLoader
parses a JSON file using json_decode
.
option | type | default | |
---|---|---|---|
optional | bool | false | Return empty config is file doesn't exist |
base_path | string | getcwd() | Basepath for relative paths |
Yaml
YamlLoader
parses a YAML file using yaml_parse
.
option | type | default | |
---|---|---|---|
num | int | 0 | Document to extract from stream (0 is first doc) |
callbacks | array | [] | Content handlers for YAML nodes |
optional | bool | false | Return empty config is file doesn't exist |
base_path | string | getcwd() | Basepath for relative paths |
The YamlLoader
is used by default if the yaml
extension is loaded.
Symfony\Yaml
YamlSymfonyLoader
is an alternative loader for YAML, using the Symfony Yaml component.
option | type | default | |
---|---|---|---|
optional | bool | false | Return empty config is file doesn't exist |
base_path | string | getcwd() | Basepath for relative paths |
When constructing the loader a Symfony\Component\Yaml\Parser
object may be passed.
use Symfony\Component\Yaml; $parser = new class() extends Yaml\Parser() { public function parse($value, $options = 0) { return parent::parseFile($value, $options | Yaml\Yaml::PARSE_CONSTANT); } } $yamlLoader = new YamlSymfonyLoader($options, $parser);
Env
EnvLoader
maps environment variables to settings. In the mapping the settings key supports dot notation.
option | type | default | |
---|---|---|---|
map | array | (required) | key/value pairs from env name to setting key |
Example
$map = [ "APP_SECRET" => "secret", "APP_DATABASE_PASSWORD" => "db.password" ]; $config->load('env', ['map' => $map]);
DynamoDB
DynamoDBLoader
allows loading settings from an AWS DynamoDB database. It expects all settings to be in a single item.
It will not do a table scan. By default the whole item is taken as settings. Alternatively, use the settings_field
option to specify a Map field that holds the settings.
option | type | default | |
---|---|---|---|
table | string | (required) | DynamoDB table name |
key_field | string | 'key' | Indexed field (typically primary index) |
key_value | string | (required) | Value to select item on |
settings_field | string | null | within the item that holds the settings |
Example
$dynamodb = Aws\DynamoDb\DynamoDbClient::factory([ 'region' => 'eu-west-1', 'version' => '2012-08-10' ]); * $config = new Jasny\Config(); $config->load($dynamodb, [ 'table' => 'config', 'key_field' => 'key', 'key_value' => 'myapp' ]);
DelegateLoader
The DelegateLoader
is a map with loaders, than can automatically pick a loader based on the file extension or class
name.
By default it holds all the loaders of this library. You may pass an array of loaders as dependency injection.
use Jasny\Config\Loader; $loader = new Loader\DelegateLoader([ 'yaml' => new Loader\YamlLoader(['base_path' => __DIR__ . '/config']), 'json' => new Loader\JsonLoader(['base_path' => __DIR__]) ]); $config = new Config([], $loader); $config->load('composer.json'); $config->load('settings.yml');
Config
The Config
object is a dynamic object; settings are added as public properties. It extends the stdClass
object.
Upon construction you can pass settings as associative array or stdClass
object.
$config = new Jasny\Config([ 'foo' => 'bar', 'db' => [ 'host' => 'localhost', 'username' => 'root', 'password' => 'god' ] ]);
Optionally you can pass a loader. If your config is only in JSON files, consider passing the JsonLoader
. This saves
the creation of the DelegateLoader and loaders for all other file types.
load()
Load new setting from file or other data source and add it to the config.
load(string|object $source, array $options = [])
This is a fluent interface, so the method returns $this
.
Example
$config = (new Config()) ->load('composer.json') ->load('config/settings.yml') ->load($dynamoDB, ['table' => 'config', 'key_value' => 'myapp']);
merge()
Merge one or more Config
(or stdClass
) objects into the config.
merge(stdClass $settings, ...)
This is a fluent interface, so the method returns $this
.
get()
The Config
object implements the PSR-11 ContainerInterface
.
The get
method finds a setting in the config by key. The dot notation may be used to get child properties.
mixed get(string $key)
If the setting doesn't exist, a Jasny\Config\Exception\NotFoundException
is thrown.
Example
$config->get('foo'); // bar $config->get('db.host'); // localhost // throws a NotFoundException $config->get('something_random');
has()
The has
method is part of the PSR-11 ContainerInterface
. It checks if a setting exists. As with get()
, the key
supports the dot notation.
bool has(string $key)
saveAsScript() / loadFromScript()
The saveAsScript()
method create parsable string representation of a variable using
var_export
and store it as a PHP script.
As described in the 500x faster caching article, storing the parsed configuration as a PHP script can make loading it much faster.
The loadFromScript()
method can be used to load the settings. It's recommended to use this function rather than just
file_exists
and include
, as checking the file exists would always hit the file system. This function checks the
opcode cache first.
$config = Config::loadFromScript('tmp/settings.php'); if (!isset($config)) { $config = (new Config()) ->load('composer.json') ->load('config/settings.yml'); $config->saveAsScript('tmp/settings.php'); }