Download the PHP package caseyamcl/configula without Composer

Configula

Configula is a configuration library for PHP 7.3+.

Use this library when you want to load configuration from the filesystem, environment, and other sources. It implements your configuration values as an immutable object in PHP. It is a framework-independent tool, and can be easily used in any PHP application.

Features

• Load configuration from a variety of sources:
  • Load values from .php, .ini, .json, and .yml configuration file types
  • Load values from the environment, and .env files using a DotEnv library (vlucas or Symfony)
  • Easily write your own loaders to support other file types and sources
• Cascade/deep merge values from multiple sources (e.g. array, files, environment, etc)
• Optionally use in combination with Symfony Config Component to validate configuration values and/or cache them
• Creates an immutable object to access configuration values in your application:
  • Array-access (read-only)
  • get(val), has(val), and hasValue(val) methods
  • Magic methods (__get(val), __isset(val), and __invoke(val))
  • Implements Traversable and Countable interfaces
• Provides simple dot-based access to nested values (e.g. $config->get('application.sitename.prefix');)
• Code quality standards: PSR-12, near-complete unit test coverage

Installation

Need PHP v7.1, 7.2 or Symfony v3 compatibility?

Configula v4.x is compatible with PHP v7.3+ or v8.0+. If you need PHP 7.1, 7.2 compatibility, instruct Composer to use the 3.x version of this library instead of the current one:

Need PHP v5.* compatibility?

Configula Version 2.x is compatible with PHP v5.3+. If you need PHP 5.x compatibility, instruct Composer to use the 2.x version of this library instead of the current one:

Upgrading?

Refer to UPGRADE.md for notes on upgrading from Version 2.x, 3.x to v4.

Loading Configuration

You can use the Configula\ConfigFactory to load configuration from files, the environment or other sources:

Or, if you are loading an array, you can instantiate Configula\ConfigValues directly:

Or, you can manually invoke any of the loaders in the Configula\Loader namespace:

Accessing Values

The Configula\ConfigValues object provides several ways to access your configuration values:

Accessing values using dot notation

Configula supports accessing values via dot-notation (e.g some.nested.var):

Property-like access to your config settings via __get() and __isset():

Iterator and count access to your config settings:

Callable access to your config settings via __invoke():

Array access to your config settings:

Merging Configuration

Since Configula\ConfigValues is an immutable object, you cannot mutate the configuration once it is set. However, you can merge values and get a new copy of the object using the merge or mergeValues methods:

Configula performs a deep merge. Nested arrays are traversed and the last value always takes precedence.

Note that Configula does not deep merge nested objects, only arrays.

Iterator and Count

The built-in ConfigValues::getIterator() and ConfigValues::count() methods flattens nested values when iterating or counting:

If you want to iterate only the top-level items in your configuration, you can use the getArrayCopy() method:

Using the Folder Loader - Config Folder Layout

The folder loaders in Configula will load files with the following extensions (you can add your own custom loaders; see below):

• php - Configula will look for an array called $config in this file.
• json - Uses the built-in PHP json_decode() function
• yaml or yml - Uses the Symfony YAML parser
• ini - Uses the built-in PHP parse_ini_file() function

The ConfigFactory::loadPath($path) method will traverse directories in your configuration path recursively.

The ConfigFactory::loadSingleDirectory($path) method will load your configuration in a single directory non-recursively.

Local Configuration Files

In some cases, you may want to have local configuration files that override the default configuration files. There are two ways to do this:

1. prefix the default configuration file extension with .dist (e.g. config.dist.yml), and name the local configuration file normally: config.yml
2. name the default configuration file normally (e.g. config.yml) and prefix .local to the extension for the local configuration file: config.local.yml.

Either way will work, and you could even combine approaches if you want. The file iterator will always cascade merge files in this order:

• FILENAME.dist.EXT
• FILENAME.EXT
• FILENAME.local.EXT

This is useful if you want to keep local configuration files out of revision control. Choose a paradigm, and simply add the following to your .gitignore

Example

Consider the following directory layout...

If you use ConfigFactory::loadPath('/my/app/config'), the files will be parsed according to their extension and values will be merged in the following order (values in files that are later in the list will clobber earlier values):

Loading from environment variables

There are two common ways that configuration is generally stored in environment:

1. As multiple environment variables (perhaps loaded by phpDotEnv or Symfony dotEnv, or exposed by Heroku/Kubernetes/etc.).
2. As a single environment variable with a JSON-encoded value, which exposes the entire configuration tree.

Configula supports both. You can also write your own loader if your environment is different.

Loading multiple environment variables

Configula supports loading environment variables as configuration values using getenv(). This is the 12 Factor App way of doing things.

Common use-cases for this loader include:

1. Loading system environment as config values
2. Loading values using phpDotEnv or Symfony dotEnv
3. Accessing values injected into the environment by a cloud provider (Kubernetes, Docker, Heroku, etc.)

Default environment variable loading

The default behavior is to load the configuration values directly:

Result:

Load only environment variables with prefix

You can load ONLY environment variables with a specific prefix. Configula will remove the prefix when loading the configuration:

Result:

Convert environment variables to nested configuration

You can convert a flat list into nested config values by passing a delimiter to break on:

Result:

This allows you to access nested values as an array:

Transform environment variables to lower-case

You can transform all the values to lower-case by passing TRUE as the last argument:

Result:

Loading environment variables with regex pattern

Instead of using a prefix, you can pass a regex string to limit returned values:

Result:

Loading a single JSON-encoded environment variable

Use the Configula\Loader\JsonEnvLoader to load a JSON environment variable:

Loading from multiple loaders

You can use the Configula\ConfigFactory::loadMultiple() to load from multiple sources and merge results. This method accepts an iterator where each value is one of the following:

• Instance of Configula\ConfigLoader\ConfigLoaderInterface
• Array of configuration values
• String or instance of SplFileInfo that is a path to a file or directory

Any other value in the iterator will trigger an \InvalidArgument exception

Handling Errors

All exceptions extend Configula\Exception\ConfigException. You can catch this exception to catch certain types of Configula errors during loading and reading of configuration values.

Loading Exceptions:

• ConfigLoaderException is thrown when an error occurs during loading configuration.
• ConfigFileNotFoundException is thrown when a required configuration file or path is missing. It is generally thrown from the FileLoader loader when the $required constructor parameter is set to true.
• UnmappedFileExtensionException is thrown from the DecidingFileLoader for files with unrecognized extensions.

NOTE: Configula does NOT catch non-Configula exceptions and convert them to Configula exceptions. If you wan to catch all conceivable errors when loading configuration, you should surround your configuration loading code with a try...catch (\Throwable $e).

Config Value Exceptions:

• ConfigValueNotFoundException is thrown when trying to reference a non-existent configuration value name and no default value is specified.
• ConfigLogicException is thrown when attempting to mutate configuration via array
• InvalidConfigValueException is not thrown from any Configula class directly, but provided as an option for implementing libraries (see "Extending the ConfigValues class" below).

Extending the ConfigValues class (for IDE type-hinting)

While it is entirely possible to use the Configula\ConfigValues class directly, you might also want to provide some application-specific methods to load configuration values. This creates a better developer experience.

Note: Notice that the example above uses the InvalidConfigValueException, which is included with Configula for exactly this use-case.

You can use your custom AppConfig class as follows:

Using Symfony Config to define a configuration schema

In some cases, you may wish to strictly control what configuration values are allowed and also validate those values when loading the configuration. The Symfony Config Component provides an excellent mechanism for accomplishing this.

First, include the Symfony Config Component library in your application:

Then, create a class that provides your configuration tree. Refer to the Symfony Docs for all the cool stuff you can do in your configuration tree:

Load your configuration as you normally would, and then pass the resulting ConfigValues object through the Symfony filter:

Writing your own loader

In addition to using the built-in loaders, you can write your own loader. There are two ways to do this:

Create your own file loader

Extend the Configula\Loader\AbstractFileLoader to write your own loader that reads data from a file.

Use it:

If you want to use the FolderLoader and automatically map your new type to a file extension, you can do so:

Create your own custom loader

Create your own implementation of Configula\Loader\ConfigLoaderInterface, and you can load configuration from anywhere:

Use it:

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

Contributing

Please see CONTRIBUTING for details.

Credits

• Casey McLaughlin
• All Contributors

License

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