Generic container class to hold data.
Generic container class to hold data.
This class is a data container and provides a number of methods to get, set, add, import and export data. See the core module documentation for more information on how to use this class efficiently.
__construct($data=null) ¶Create a new AnewtContainer instance.
An optional parameter can be supplied to fill the container with initial values. This is the same as calling seed() manually. You may safely override the constructor for your own classes; there is no need to call the parent constructor.
$dataAn associative array with the initial data (optional)
These methods can be used to get and set data. These methods may call into special getter and setter methods. Most methods have a corresponding non-magic method that does not invoke special getter and setter methods.
get($name) ¶Return the data referenced by name.
By default just returns the data referenced by $name. If you write a class that extends AnewtContainer, you can write special methods to override the behaviour of the AnewtContainer::get() function. In order to do this, you can write a get_foo() method which will be invoked if you use get('foo'). This allows for a consistent API, optional getter and setter methods and on-the-fly generation of data.
This method supports basic caching of values. If you write a get_foo_() method (note the trailing underscore!) and you call $obj->get('foo'), the value will be cached and your special method will only be called once. Note that regular getters, eg. get_foo() always have precedence over the caching methods. You should provide either get_foo() or get_foo_(), not both. This type of caching is very useful if you do database queries or other computationally intensive things in your getter method and you only need to do it once per instance.
$nameThe name of the value to get
The requested data.
getdefault($name, $default=null) ¶Return the data by name, or a default value.
$nameThe name to get.
$defaultThe default value, in case no value was set
set($name, $value) ¶Store a value in the container.
You can write special methods like set_foo() accepting a variable number of parameters to override the default behaviour of this methods. See the documentation for AnewtContainer::get() for more information.
$nameThe name of the data to store (int or string).
$valueThe value of the data to store.
setdefault($name, $default) ¶Set a default value if no value was previously set.
This method checks if the variable referenced by $name is set. If not, it sets the default value. If the variable is already set, this method does nothing at all.
$nameThe name to set
$defaultThe default value to store, in case no value was set before
add($name, $value) ¶Add data to a list.
You can write special methods like add_foo() accepting a variable number of parameters in classes extending AnewtContainer. See the documentation for AnewtContainer::get() for more information.
$nameThe name of the data to store (int or string).
$valueThe value of the data to add.
delete($name=null) ¶Delete a value from the container.
This method is only useful for simple data fields (i.e. without custom getter/setter methods) and for those with cached get methods. In the last case, unsetting the saved data will make sure the data is 'invalidated', so the get-method gets re-executed the next time the value is needed.
$nameThe name of the data to unset (int or string).
is_set($name) ¶Check whether a value for the name specified exists.
This methods checks whether a value exists for the specified name, or whether a special getter function for it exists. Use this method if you want to be sure you can call get($name) without errors later on.
$nameThe name of the data to check for (int or string).
True if the data is available, false otherwise.
seed($data, $keys=null) ¶Seed the container with data.
This method lets you populate the container instance with data from an associative array, e.g. a database result or a hardcoded array of initial values.
$dataAn array or object containing data. Both numeric, associative and mixed arrays are supported, as well as AnewtContainer objects (or anything that provides a valid to_array() method.
$keysOptional parameter that is used to selectively seed this container with data. If used in combination with an array of $data, this parameter is treated as a list of keys that should be used. If used in combination with an $data object, the parameter is passed to $obj->to_array() unmodified.
clear() ¶Remove all data from the container.
This removes all values from the internal storage. Magic getter methods may still yield results afterwards, but the internal storage will be empty. Usually you don't need this method: use a new instance if you want to work with a different set of data.
keys() ¶Return a list of all defined names.
This method includes both keys in the internal storage and the name of values available only through getter methods.
A numeric array with all keys.
to_array($keys=null) ¶Export all available data to an associative array.
This method tries its best to get all the available data. It returns all the variables stored in the internal __data storage and calls all get_* methods too (this is off by default). Advanced getter methods that take parameters should provide a default value, otherwise the conversion is not going to work. Note that if both internal storage and getters are available for the same data, the latter has precedence, eg. the internal storage is ignored.
$keysA numeric array or a boolean value. If a numeric array is supplied it will be used as a list of keys (passed to the get() method of the $container). If boolean false is supplied, only the internal data of the container is returned and special getter methods are not invoked. If a boolean true is supplied, all data including the data returned by special getter methods on the container is returned. Note that using boolean true might result in a very expensive operation (all getter methods are invoked!), so it should be used with care. If omitted (or null), this parameter defaults to boolean false (only internal container storage is returned).
An associative array containing all the data from this container.
These methods have roughly the same API as their magic counterparts, but don't call special getter and setter methods, so they work for simple values only. This is considerably faster if you're e.g. looping over many AnewtContainer instances and extracting some values.
_getdefault($name, $default=null) ¶Return the data by name, or a default value (non-magic).
$nameThe name to get.
$defaultThe default value to return if no value for $name was stored before.
The associated value or the default value supplied.
_set($name, $value) ¶Store a value in the container (non-magic).
$nameThe name of the data to store.
$valueThe value of the data to store.
_add($name, $value) ¶Add data to a list (non-magic).
$nameThe name of the list to add to.
$valueThe value of the data to add.
_isset($name) ¶Check whether a value for the name specified exists (non-magic).
$nameName to check for.
True if set, false otherwise.
_seed($data) ¶Populates the internal array from an array (non-magic).
$dataAn associative array with data.
_to_array() ¶Export all name-value pairs to an associative array (non-magic).
This method does not call into getter methods.
Array (copy) containing the internal storage.