Vars
Vars is a simple to use and easily extendable configuration file loader for PHP with built-in support for env, INI, JSON, PHP, Toml, XML and YAML config file types. Contains a service provider for Silex, more frameworks to come soon.
Install / Use
/learn @m1/VarsREADME
Vars
[![Latest Version on Packagist][ico-version]][link-packagist]
![Software License][ico-license]
[![Build Status][ico-travis]][link-travis]
[![Coverage Status][ico-scrutinizer]][link-scrutinizer]
[![Quality Score][ico-code-quality]][link-code-quality]
[![Total Downloads][ico-downloads]][link-downloads]
Vars is a simple to use, lightweight and easily extendable configuration loader with built-in loaders for ENV, INI, JSON, PHP, Toml, XML and YAML file types. It also comes built-in support for Silex with more frameworks (Symfony, Laravel etc) to come soon.
- Why?
- Requirements
- Install
- Usage
- Todo
- Change log
- Testing
- Contributing
- Security
- Credits
- License
Why?
Sometimes you're forced to use different formats for config files and one of Vars aims is to make this simpler for you by supporting the most common config formats so you don't have to switch libraries to deal with the different formats.
Another aim is to support different frameworks so again you don't have to switch libraries when dealing with different frameworks. Currently only supporting Silex using a service provider, support for Laravel and Symfony to follow shortly.
With a simple API and intuitive loading options, Vars tries to make config loading and providing as easy as possible for you.
Requirements
Vars requires PHP version 5.3+.
If you want to use YAML you'll need the symfony/yaml library and similarly you'll need yosymfony/toml to use Toml files and m1/env to use Env files.
Install
Via Composer
$ composer require m1/vars
Usage
Basic
// load single file
$vars = new Vars(__DIR__.'/config/config.yml');
// load from dir
$vars = new Vars(__DIR__.'/config');
// load from array
$vars = new Vars(array(
__DIR__.'/config/config.yml',
__DIR__.'/config/sub',
));
Accessing the config
This can be done in various ways, you can treat the $vars variable as a normal array or you can use it in a object oriented manner
// All return the same thing
$vars->get('db.password')
$vars['db.password'];
$vars['db']['password']
You can also set values in the same manner
// All do the same thing
$vars->set('db.password', 'test')
$vars['db.password'] = 'test';
$vars['db']['password'] = 'test';
You can also get the variables from getenv()
// All do the same thing
$vars->toEnv();
getenv('db.password');
For more info on this check the Environment Variables section
Importing
Importing files
You can easily relatively and absolutely import configs into other configs, these differ by the config file type so check the /tests/mocks/ folder for examples
# example_1.yml
test_key_1: test_value_1
imports: example_2.yml
# example_2.yml
test_key_2: test_value_2
Would return:
[
"test_key_1" => "test_value_1",
"test_key_2" => "test_value_2"
]
Imports are imported relative to the key by default, eg:
test_key_1:
imports: example_2.yml
Would return:
[
"test_key_1" => [
"test_key_2" => "test_value_2"
]
]
However you can change this various ways:
# example 1
test_key_1:
imports:
- {resource: example.yml, relative: false}
# example 2
test_key_2:
imports:
resource: example.yml
relative: false
If importing various files and you want to set the relativity of all files you can do the following:
test_key_1:
imports:
relative: false
resource:
- example_2.yml
- example_3.yml
All the above cause the example_2.yml and example_3.yml variables to become absolute to the config file:
[
"test_key_1" => []
"test_key_2" => "test_value_2" // from example_2.yml
"test_key_3" => "test_value_3" // from example_3.yml
]
Importing directories
You can also import directories using all of the above syntax:
test_key_1:
imports: sub/
Importing directories is by default not recursive and will not search folders within folders, you can change this by adding a recursive toggle:
test_key_1:
imports:
resource: sub/
recursive: true
or by adding a recursive flag:
test_key_1:
imports:
resource: sub/*
As with the loading files, you can bulk import dirs with one recursive toggle:
test_key_1:
imports:
recursive: false
resource:
- sub/
- sub1/
The importing of directories relies on loaders and the extensions supported by the loaders. See the loader section for more detail.
Flag options
You can use various flags when importing.
The if else flag ?: makes it so if the first file exists, use that -- else use the other defined file, eg:
imports: "example_1.yml ?: example_2.yml"
Note: You need to wrap the string in quotes for the if else flag to work
The suppress exceptions flag @ -- suppresses files not found exceptions. eg:
imports: @file_does_not_exist.yml
The recursive flag makes it so directories within directories are searched for files. eg:
imports:
resource: sub/*
You can also combine the above flags, so if the else file option does not exist, it won't throw an exception, eg:
imports: "example_1.yml ?: @example_2.yml"
Resources
You can get individual files or resources:
// All return the same thing
$vars->getResource('example_2.yml')->get('test_key_2');
$vars->getResource('example_2.yml')['test_key_2'];
Options
There are various options for Vars
$vars = new Vars(__DIR__.'/config/config.yml', [
// this will affect how you getResource() and will default to the path
// of the first resource you initiate
'path' => __DIR__.'/config',
// to cache or not -- defaults to true
'cache' => true,
// where the cache is stored -- If not set will default to the base path
'cache_path' => __DIR__.'/config/',
// How long the cache lasts for -- Defaults to 300 seconds (5 minutes)
'cache_expire' => 300,
// Replacement variables -- see variables section for more detail
'replacements' => [
'foo' => 'bar',
'foobar' => 'barfoo'
],
// Merge globals -- see globals section for more detail
'merge_globals' => true,
// The file loaders to load the configs -- see loader section for more detail
'loaders' => [
'default'
]
]);
Base path
The path is how the $filename in $vars->getResource($filename) is calculated. For example:
If you set the path to __DIR__.'/config' and you imported __DIR__.'/app/test_1.yml':
# example_1.yml
imports: example_2.yml
Then both the example_1.yml and example_2.yml $filename would be ../app/test_1.yml and ../app/test_1.yml respectively.
If no path is set then the first file resource path will be used as the path, eg:
// example 1
$vars = new Vars(__DIR__.'/config/config.yml');
// example 2
$vars = new Vars([
__DIR__.'/config/config.yml',
__DIR__.'/sub/config.yml',
]);
Will both use __DIR__.'/config' as the path
Variables
You can use 3 types of variables in Vars: Replacements, In-file and Environment, the syntax is:
| Variable Type | Syntax |
| ------------- | ------------- |
| Replacements | %VARIABLE% |
| In-file | %$VARIABLE% |
| Environment | %^VARIABLE% |
For better readability you can also put spaces between the variable name and the prefix/suffixes like so:
replacement_variable: % VARIABLE %
infile_variable: %$ VARIABLE %
env_variable: %^ VARIABLE %
Replacements
Replacement variables are loaded from outside Vars, so it's often used for PHP functions/logic, such as __dir__:
test_key_1: %foo%
test_key_2: /bar/%foobar%/bar
$vars = new Vars(__DIR__.'/config/config.yml', [
'replacements' => [
'foo' => 'bar',
'foobar' => 'barfoo'
],
]);
Outputs:
[
"test_key_1" => "bar",
"test_key_2" => "/bar/barfoo/foobar/"
]
Your replacements must be prefix and suffixed with %
You can also load variables from files:
$vars = new Vars(__DIR__.'/config/config.yml', [
'replacements' => __DIR__.'/config/variables.yml'
]);
In-file Variables
You can also use variables from your alrea
