…igurations

The merging is done in three steps:

    1. Normalization:
    =================
    All passed config arrays will be transformed into the same structure
    regardless of what format they come from.

    2. Merging:
    ===========
    This is the step when the actual merging is performed. Starting at the root
    the configs will be passed along the tree until a node has no children, or
    the merging of sub-paths of the current node has been specifically disabled.

       Left-Side       Right-Side      Merge Result
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       -nothing-       array           Right-Side will be taken.
       scalar          scalar          Right-Side will be taken.
       array           false           Right-Side will be taken if ->canBeUnset()
                                       was called on the array node.
       false           array           Right-Side will be taken.
       array           array           Each value in the array will be passed to
                                       the specific child node, or the prototype
                                       node (whatever is present).

    3. Finalization:
    ================
    The normalized, and merged config will be passed through the config tree to
    perform final validation on the submitted values, and set default values
    where this has been requested.

You can influence this process in various ways, here is a list with some examples.
All of these methods must be called on the node on which they should be applied.

  * isRequired(): Node must be present in at least one config file.
  * requiresAtLeastOneElement(): PrototypeNode must have at least one element.
  * treatNullLike($value): Replaces null with $value during normalization.
  * treatTrueLike($value): Same as above just for true
  * treatFalseLike($value): Same as above just for false
  * defaultValue($value): Sets a default value for this node (only for scalars)
  * addDefaultsIfNotSet(): Whether to add default values of an array which has not
                           been defined in any configuration file.
  * disallowNewKeysInSubsequentConfigs(): All keys for this array must be defined
                                          in one configuration file, subsequent
                                          configurations may only overwrite these.
  * fixXmlConfig($key, $plural = null): Transforms XML config into same structure
                                        as YAML, and PHP configurations.
  * useAttributeAsKey($name): Defines which XML attribute to use as array key.
  * cannotBeOverwritten(): Declares a certain sub-path as non-overwritable. All
                           configuration for this path must be defined in the same
                           configuration file.
  * cannotBeEmpty(): If value is set, it must be non-empty.
  * canBeUnset(): If array values should be unset if false is specified.

Architecture:
=============
The configuration consists basically out of two different sets of classes.

  1. Builder classes: These classes provide the fluent interface and
                      are used to construct the config tree.

  2. Node classes: These classes contain the actual logic for normalization,
                   merging, and finalizing configurations.

After you have added all the metadata to your builders, the call to
->buildTree() will convert this metadata to actual node classes. Most of the
time, you will not have to interact with the config nodes directly, but will
delegate this to the Processor class which will call the respective methods
on the config node classes.