Docs For Class midcom_helper

Description

This class is designed to ease MidCOM Configuration management.

Basically it supports key/value pairs of data, which can be retrieved out of Midgard Parameters. In this case it would make the key/values a string/string pair with a length limit of 255 characters. Since the current implementation only supports read-access to the configuration data, this is a neglible fact, in reality it supports all valid PHP data types as key or data values, as long it is allowed to use the keys as array index elements.

This class is designed to manage parameter like key/value configuration data. The class makes no assumption about the value type of keys or values, any valid PHP data type is allowed. Two different sets of configuration options are stored within the class, the "global" and the "local" configuration.

The global configuration must include all possible configuration parameters with their default values. These data is fixed and cannot be changed after object instantination. Aimed specifically at MidCOM is the second set of configuration data, the "local" parameters. It gives you a way of explicitly overwrite a part of the configuration data with localized values. This customization data can be overwritten at wish by deliberatly resetting it to the defaults or by importing a new one over the existing local configuration.

Configuration data can be delivered in two ways: The easiest way is using a acciociative array that will be used as configuration. Alternativly you can specify both a MidgardObject and a MidCOM Path which is used to fetch configuration data.

Any configuration key in the local configuration, which is not present in the global "template", will be logged as a warning into the MidCOM log. This should normally not happen. Originally, this case threw a critical error, but that made upgrading configurations quite difficult.

Located in /midcom/helper/configuration.php (line 46)

Variable Summary

Array $_global

Array $_local

Array $_merged

Method Summary

midcom_helper_configuration midcom_helper_configuration ([mixed $param1 = NULL], [mixed $param2 = NULL])

bool exists (string $key)

mixed get (mixed $key)

Array get_all ()

void reset_local ()

bool store (Array $params, [bool $reset = true])

bool store_from_object (MidgardObject $object, string $path)

void _check_local_array (mixed $array)

void _store_from_object (MidgardObject $object, string $path, [bool $global = false])

void _update_cache ()

Variables

Array $_global (line 54)

Globally assigned configuration data.

access: private

Array $_local (line 62)

Locally overriden configuration data.

access: private

Array $_merged (line 70)

Merged, current configuration state.

access: private

Methods

Constructor midcom_helper_configuration (line 87)

The constructor initializes the global configuration.

Two sources can be specified:

First, if passed a single accociative array to the constructor, it will use its contents as global configuration.

Alternativly you can specify any Midgard object and a parameter domain. It will then use the contents of this domain as global configuration.

midcom_helper_configuration midcom_helper_configuration ([mixed $param1 = NULL], [mixed $param2 = NULL])

mixed $param1: Either an accociative array or a reference to a Midgard object.
mixed $param2: Either null or the name of a Parameter domain.

exists (line 296)

Checks for the existence of a configuration key.

return: True, if the key is available, false otherwise.

bool exists (string $key)

string $key: The configuration key to check for.

get (line 269)

Retrieve a configuration key

If $key exists in the configuration data, its value is returned to the caller. If the value does not exist, the boolean value false will be returned. Be aware that this is not always good for error checking, since "FALSE" is a perfectly good value in the configuration data. Do errorchecking with the function exists (see below).

return: Its value of FALSE, if the key doesn't exist.
see: midcom_helper_configuration::exists()

mixed get (mixed $key)

mixed $key: The configuration key to query.

get_all (line 285)

Retrieve a copy the complete configuration array.

return: The complete current configuration.

Array get_all ()

reset_local (line 251)

Clear the local configuration data, effectively reverting to the global default.

void reset_local ()

store (line 217)

The method store will write the parameters in $params into the local configuration.

If $reset is set, the local configuration will be cleared before the new set is imported, if not, the new data is merged with the old local configuration, overwriting duplicates. During import each configuration key will be checked against the global configuration values. If an unkown value is found, import will be aborted and no changes to the configuration is done.

After import the cache array will be updated, reset is done by reset_local.

return: Indicating success.
see: midcom_helper_configuration::reset_local()

bool store (Array $params, [bool $reset = true])

Array $params: The new local parameters
bool $reset: If set to true, the current local configuration will be discarded first.

store_from_object (line 243)

Import data from a Midgard object.

To import configuration data from an Midgard Object, use this method. As in the respecitve constructor it will retrieve the configuration data in the parameter domain $path of $object. Unlike the constructor this function will store the data in the local configuration.

return: Indicating success

bool store_from_object (MidgardObject $object, string $path)

MidgardObject $object: The object from which to import data.
string $path: The parameter domain to query.

_check_local_array (line 186)

Check local data array for validity

Since the local array must only include configuration parameters that are included in the global configuration, this function is used to check a local array against the current global configuration. true/false is returned accordingly.

On any inconsistency a WARNING level message is logged, but the error is silently ignored as of 2.4.0.

access: private

void _check_local_array (mixed $array)

_store_from_object (line 126)

This function will fetch the configuration data stored in the parameter domain $path of the Midgard Object $object.

The flag $global controls whether the global or the local configuration should be updated. No control whether an update of the global data is allowed is done here, the caller has to do this. This function will update the config data cache array. If it stores global configuration data it will automatically erase the local configuration data.

Any error such as invalid configuration data will trigger an MidCOM error.

access: private

void _store_from_object (MidgardObject $object, string $path, [bool $global = false])

MidgardObject $object: The object from which to retrieve the configuration.
string $path: The Parameter domain to query.
bool $global: Set to true to replace the global configuration.

_update_cache (line 165)

This method will merge the local and the global configuration arrays into the cache array.

access: private

void _update_cache ()