Download the PHP package flying/config without Composer

Object configuration implementation

Overview

This package provides simple, fast and flexible implementation of object's configuration management.

It is pretty common task for objects to have some configuration options that somehow affects their behavior. Usually this functionality is implemented:

• As a set of configurable properties with either corresponding getter/setter pairs for each property (example)
• Array with configuration options and corresponding accessors
• Use of external configuration class

Or as some kind of mix of these ways.

First way is most common, however it have some drawbacks:

• It is hard to pass changes to multiple properties between objects
• It is hard to implement temporary changes to object's configuration for single method call

This package implements second of described ways of objects configuration - through accessors to object's configuration options.

Highlights

• Arbitrary configuration options are supported, defined by class
• Configuration values are always validated before use to make sure that configuration is always valid
• Expansion of given partial configuration is fully supported
• Full support for configuration inheritance and extending into nested classes
• Implemented both as abstract base class to inherit from and as standalone class to use separately
• Hook for implementing custom logic upon configuration change is provided

Basic usage

Package provides two different ways to use its functionality - base class to inherit your classes from and standalone implementation to use in arbitrary classes.

Use of base class implementation

Minimum requirement to use base class implementation - is definition of class configuration options.

Configuration options definition

Configuration options definition is implemented by overloading method. Overloading should be done in a way described in method itself to make sure that configuration inheritance will work properly.

Let's say we're configuring some kind of file-based cache provider:

At this point we're ready to use defined configuration options. We can get some configuration values:

or set them one by one

or multiple values at once

but at this point we can't be sure that our configuration is valid at any point of time. To achieve this - it is necessary to implement configuration validator.

IMPORTANT: Starting from version 2.0.0 only scalar and array configuration options can be passed to because configuration initialization results are now cached for better performance. Passing any kind of dynamic values (e.g. array of objects) to may cause unwanted side effects, but not controlled for performance reasons.

Configuration validation

To make configuration valid - we need to implement one more method: . This method receives name and value of configuration option and should decide if configuration option can be changed in this way and, optionally, can normalize given value. For example validator for our example configuration may look like this:

After implementing this method we can be sure that our configuration will be valid at any time.

Lazy configuration initialization

As of v1.1.0 it is possible to perform lazy (upon request) initialization of configuration options. It is especially helpful in a case if configuration options contains some information that is expensive to initialize by default, e.g. object instances. To initialize some configuration option lazily you need to set its default value to and implement option initialization into method. For example:

and later in code:

If your object configuration is planned to be completely initialized in a lazy way - you can simplify your configuration initalization:

Partial configuration expansion

Sometimes it may be necessary to run some object's method with different configuration. This can be done by passing additional configuration options to method itself as additional argument. But in general case we can't be sure that given set of configuration options is complete (and not just 1-2 options) and we know nothing about its validity. This package have great support for handling such situations. Let's take a look at example:

You can see how simple it is. With just one line of code we got:

• Complete set of object's configuration options
• Ensure that all configuration options in this variable are valid
• Ensure that all given modifications to configuration options are validated and applied

And actual object's configuration is not modified, so we can work with our local, possibly modified copy of configuration while keeping actual configuration pristine.

Configuration modifications

Sometimes it may be necessary to modify our local copy of object's configuration and do it in a safe way to be sure that our configuration is still complete and valid. It can be achieved by using method. It accepts configuration options array, applies given modifications to it and returns resulted configuration.

Various configuration sources

Sometimes it may be necessary to import object's configuration from another object. It can be done by passing such object (e.g. or something like this) directly to method.

Configuration inheritance and extension

It is often required to extend list of configuration options into child classes. This functionality will be achieved automatically as long as and methods will be implemented in a way described in these methods (or this document).

Configuration change tracking

It is often necessary to perform some additional tasks upon change of object's configuration. It can be done by overriding method. It is called each time after configuration option is changed. Name and new value of configuration option are given as arguments to this method. Good practice for implementation of this method would be to follow same structure as for method to ensure proper work of application's logic in a case of inherited classes.

Use of standalone implementation

Standalone implementation is provided by class and provides same API and base implementation. Fully-functional usage example can be seen into corresponding test class.

It can be seen that it is generally may be good idea to implement for such objects and proxy all methods to internal configuration object. In this case your object with standalone version of configuration functionality will be functionally equal to objects inherited from .

Implementation details

For flexibility and performance reasons configuration options are stored and passed as arrays. To distinguish object's configuration from regular arrays - they have additional entry (defined in ).

Existence of this entry should be taken in mind when, for example, iterating over configuration options list:

If you need to avoid getting this additional entry - you can pass as second argument to method (only in 2.x version). However it is usually bad idea to drop this entry if you plan to pass this configuration options somewhere because it will cause configuration re-validation on next access that may cause small performance penalty. Another decision made for performance reasons: arrays that contains configuration id key are automatically treated as valid and not re-validated. It is your obligation to not modify configuration arrays by hands, you need to use method instead.