Theory of Operation

Configuration data are made accessible to Zend\Config\Config's constructor via an associative array, which may be multi-dimensional so data can be organized from general to specific. Concrete adapter classes adapt configuration data from storage to produce the associative array for Zend\Config\Config's constructor. If needed, user scripts may provide such arrays directly to Zend\Config\Config's constructor, without using a reader class.

Each value in the configuration data array becomes a property of the Zend\Config\Config object. The key is used as the property name. If a value is itself an array, then the resulting object property is created as a new Zend\Config\Config object, loaded with the array data. This occurs recursively, such that a hierarchy of configuration data may be created with any number of levels.

Extending Zend\Config\Config class

If you decide to extend Zend\Config\Config class, each property (subnode) becomes the same type as the parent class. For example:

class ExtendedConfig extends Zend\Config\Config
{
}

$config = new ExtendedConfig(['node' => ['key' => 'value']]);

echo get_class($config->node);
// the result of above is ExtendedConfig not Zend\Config\Config!

This casting occurs in the constructor, which uses the construct new static() for any array subvalues it encounters when traversing the provided array. As such, we DO NOT RECOMMEND extending the constructor; instead, create a named constructor:

class ExtendedConfig extends Zend\Config\Config
{
    public static function createWithDefaults()
    {
        return new self([ /* ... */ ]);
    }
}

Zend\Config\Config implements the Countable and Iterator interfaces in order to facilitate simple access to configuration data. Thus, Zend\Config\Config objects support the count() function and PHP constructs such as foreach.

By default, configuration data made available through Zend\Config\Config are read-only, and an assignment (e.g., $config->database->host = 'example.com';) results in an exception. This default behavior may be overridden through the constructor, allowing modification of data values. Also, when modifications are allowed, Zend\Config\Config supports unsetting of values (e.g., unset($config->database->host)). The isReadOnly() method can be used to determine if modifications to a given Zend\Config\Config object are allowed, and the setReadOnly() method can be used to stop any further modifications to a Zend\Config\Config object that was created allowing modifications.

Modifying Config does not save changes

It is important not to confuse such in-memory modifications with saving configuration data out to specific storage media. Tools for creating and modifying configuration data for various storage media are out of scope with respect to Zend\Config\Config. Third-party open source solutions are readily available for the purpose of creating and modifying configuration data for various storage media.

If you have two Zend\Config\Config objects, you can merge them into a single object using the merge() function. For example, given $config and $localConfig, you can merge data from $localConfig to $config using $config->merge($localConfig);. The items in $localConfig will override any items with the same name in $config.

Merging requires modifications

The Zend\Config\Config object that is performing the merge must have been constructed to allow modifications, by passing TRUE as the second parameter of the constructor. The setReadOnly() method can then be used to prevent any further modifications after the merge is complete.