phpDocumentor

Configuration

Introduction

phpDocumentor's configuration module provides the application with the ability to load configuration from disk and augments that with the information provided by the user when they started phpDocumentor.

In doing this it populates an entity of class phpDocumentor\Configuration\Configuration and adjusts this when newer configuration options become available.

Please note: this is a mutable object that may change during the life cycle of the application by design.

The configuration object is not meant to replace parameters in the dependency injection container or internal variables, for this phpDocumentor has an Dependency Injection Container. The configuration object is meant for all options and parameters that users of the application may need to consume. Examples of such options is where to write the documentation to (target) or the list of files that it should parse.

In the appendix of this chapter an overview of the configuration structure is given, including a description of the function of each element and section.

Consuming configuration in services

There are two ways of consuming configuration options in your services:

configuration files are loaded on run-time, after the symfony service configuration has happened.

Pipeline stages

This is the recommended method as it decouples your service from the configuration object, making it easier to make changes to either class in the future.

The backbone of phpDocumentor is a pipeline with a series of stages; each stage receives a Payload object that, among other things, contains a configuration array. This configuration array contains the latest version of the configuration and the command line options merged into it.

In your stage you can read this array to grab the options you need for your service and inject them on run time.

Injecting the configuration object

When using the auto-wiring options of the Dependency Injection Container (which are the default in phpDocumentor) you can inject the configuration object by defining a constructor argument with the typehint `phpDocumentor\Configuration\Configuration`.

This is a straightforward way to receive and read the configuration but has several downsides, which is why using a Configurator is recommended:

How is the configuration read?

The Configure stage is responsible for loading the configuration files using the ConfigurationFactory. This factory supports versioning of configuration files by reading the configVersion from the root of the XML configuration file and finding the appropriate Configuration Definition.

When a Configuration Definition is found, the loaded XML file is processed by it and normalized afterwards. You can add more advanced normalization by implementing the Normalizable interface in your definition and adding rules in your normalize method that will transform your configuration array.

At this point, the ConfigurationFactory determines if the configVersion is the latest version known by phpDocumentor. This can defined in the service definition for the ConfigurationFactory, the last version in the array of definitions is considered the last.

If the configVersion is insufficient, then the ConfigurationFactory will try to upgrade the generated configuration array to the latest version by using the upgrade method of the 'old' definition. This will generate a new input for another configuration definition and the process starts all over again. This will loop until no newer configuration is found.

Adding a new version of the configuration

configuration for an example.

Search results