PHPLights/Documentation/Interfaces/LsConfigIface

Synopsis

interface LsConfigIface
{
  public function get( $name, $default = NULL );
  public function set( $name, $value );
  public function has( $name );
  public function addFile( $key, $file );
}

Description

PHPLights allows multiple ways of storing configuration data of applications. The most often used method is to store them in PHP files whose associative arrays can be added natively to the runtime configuration. However, different file formats or storage mechanisms (like database tables) are possible.

New configuration classes can implement LsConfigIface but the better way is to inherit from LsConfig. This class already implements the get(), set() and has() functions and thus, the new class must only provide the specific addFile() method.

Public functions

get()

public function get( $name, $default = NULL );

Returns the configuration value associated to the string in $name. If $name wasn't set before and is thus undefined, the value of $default is returned. It's NULL unless specified differently via the second parameter.

The configuration values can be of hierarchical nature where a set of options is stored underneath one or more parent nodes. To access values down the tree, the value of $name must be similar to a Unix path in a file system. The path components are separated by slashes ("/") and must specify the full path beginning from the root node, e.g. "/my/requested/value".

If the path doesn't point to a leaf node which only contains a single value, an associative array of all subnodes is returned. The subnodes itself can also contain further nodes or values.

set()

public static function set( $name, $value );

Stores a new value inside the configuration or overwrites an existing one if it already exists. Setting values using this function makes them available until the user request is finished and the memory is freed by the PHP interpreter. It doesn't save them to a stable storage like the hard disk. If values should be available between requests, please use a class implementing the LsStorageIface interface.

Like get(), this function can also accept a path (e.g. "/path/to/new/value") to the node where the value should be stored. Non-existing parent nodes will be created before the value is stored.

The data types given via $value can be of any type but most often scalar types like strings or numbers are used. It's also possible to set arrays to the configuration whose entries are available afterwards using the appropriate path:

set( '/fruits', array( 0 => 'apple', 1 => 'orange' ) );
$fruit = get( '/fruits/1' );

In this case $fruit will contain the string 'orange' and the example will also work with associative arrays.

The function doesn't return any value.

has()

public function has( $name );

This function allows you to test if the parameter exists in the configuration. It returns a boolean value which is TRUE if it exists and FALSE if not.

The parameter name can be a path like in get() or set() in order to test for subnodes or values deep down the tree of configuration options.

addFile()

public function addFile( $key, $file );

The implementations of addFile() are unique across all classes implementing LsConfigIface. They provide a specialized method for reading the configuration from a stable storage (e.g. the hard disk), parse them into a usable form for fast access in memory and add the new parameter to the existing ones.

The value of $key will be used as the first path element where all further nodes and values are added underneath. If e.g. the value of $key is "stmts", then the parameter "list" could be accessed by "/stmts/list".

The content of $file is always a reference to the place where the configuration is stored. This required value can differ between the implementations but is most often a string. It could be a path to a file on disk or an access string to a server where the parameter are stored.

This function doesn't return any value.