Download the PHP package m1/vars without Composer

Vars

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
  • Basic
  • Accessing the config
  • Importing
    • Files
    • Directories
    • Flag options
  • Resources
  • Options
    • Path
    • Variables
      • Replacement Variables
      • In-file Variables
      • Environment Variables
    • Caching
    • Loaders
  • Providers
    • Silex
  • Public API
    • Vars
      • Constructor
      • getContent
      • getResource
      • getResources
      • toEnv
      • toDots
      • set
      • get
    • FileResource
      • getRawContent
      • getContent
      • get
• 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

Usage

Basic

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

You can also set values in the same manner

You can also get the variables from getenv()

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

Would return:

Imports are imported relative to the key by default, eg:

Would return:

However you can change this various ways:

If importing various files and you want to set the relativity of all files you can do the following:

All the above cause the example_2.yml and example_3.yml variables to become absolute to the config file:

Importing directories

You can also import directories using all of the above syntax:

Importing directories is by default not recursive and will not search folders within folders, you can change this by adding a recursive toggle:

or by adding a recursive flag:

As with the loading files, you can bulk import dirs with one recursive toggle:

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:

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:

The recursive flag makes it so directories within directories are searched for files. eg:

You can also combine the above flags, so if the else file option does not exist, it won't throw an exception, eg:

Resources

You can get individual files or resources:

Options

There are various options for Vars

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':

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:

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:

For better readability you can also put spaces between the variable name and the prefix/suffixes like so:

Replacements

Replacement variables are loaded from outside Vars, so it's often used for PHP functions/logic, such as __dir__:

Outputs:

Your replacements must be prefix and suffixed with %

You can also load variables from files:

In-file Variables

You can also use variables from your already defined keys in the files, such as:

Outputs:

Your replacements must be prefix with %$ and suffixed with %.

For both in-file and replacements, you can use the dot notation syntax to get in arrays, e.g:

Outputs:

Environment Variables

You can also use environment variables to do replacements:

Outputs:

Your environment variables must be prefix with %^ and suffixed with %

You can also make it so your config array is available to getenv():

Note: Your config will be flattened to a dot notation for this, e.g.:

Will be accessed by:

Globals

Globals in Vars refer to variables defined as such:

Basically they are just encapsulated in an _globals array -- the use of these are so you can access them from getGlobals() from Vars

The default action is to merge them into the other file contents, so that:

Becomes:

But you can override this by changing merge_globals to false via the options.

If this doesn't make sense then you probably won't need to use globals at all, but they're useful for working with framesworks which encapsulate everything under say $app and you want to be able to access some key => values like so: $app['test_key_1']. See the Silex provider section for more examples.

Caching

Vars automatically caches the resources for 5 minutes, you can turn this off by setting the cache option to false.

The cache_path if not set is set to what the path is set to. The cache_path must be writeable.

To invalidate the cache, simply just remove the folder inside your cache_path called vars, eg: rm -rf /var/www/application/app/cache/vars

The cache file is a .php file due to the extra speedup of opcache.

If you're using the Silex provider, then the cache will not be used and set if you're in debug mode.

Loaders

The loaders are what enable Vars to read the different file types (defaults are Ini, Json, Php, Toml, Xml and Yaml).

You can enable and disable loaders via the options:

Default loads all the default loaders:

To create your own custom loader you must extend M1\Vars\Loader\AbstractLoader, have the supported extensions in the public static $supported array and have a public function load() that loads the content of the file.

Here is a primitive example that loads .txt files:

Then to use this loader, you would simply use:

Note: don't use this loader for real, it is purely for presentational purposes

Providers

Silex

It's pretty straightforward to use this library with Silex, just register it when you register other service providers:

Then you can access your config from $app['vars']

Note: If you $app['debug'] = true then the cache will not be used.

You can also access the config values from $app by using the dot notation, e.g:

You can get the above using the dot notation like so:

You can also merge globals into $app like so:

Note the $app['vars.merge']() -- This overrides the service provider defaults so in this example monolog will use the log file defined in the vars config.

You must call vars.merge after you've called the service providers you provide config values for in your config.

You can also access test_key_1 via $app['vars.test_key_1'] and similary if you want, you can access globals like so $app['monolog.logfile'].

Public API

Vars

Vars($resource, $options = array())

The constructor to create a new Vars config:

getContent()

Returns the parsed content of all the configs.

getResource($resource)

Get a specified resource, returns a file resource or false if resource doesn't exist.

The $resource name is based on the path defined in base path and the filename.

getResources()

Returns all the resources imported, they will be FileResource objects.

toEnv()

Makes it so the config is available via getenv():

toDots()

Makes it so the config is flattened into a dot notation array

getGlobals()

Gets the values defined in _globals

set($key, $value)

Set a config key:

get($key)

Gets a config key:

FileResource

getRawContent()

Get the raw, unparsed content from the file

getContent()

See getContent()

get($key)

See get()

Todo

• Add more providers (Symfony, Laravel, etc)

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• m1
• All Contributors

License

The MIT License (MIT). Please see License File for more information.