Source for file Container.php
Documentation is available at Container.php
// +---------------------------------------------------------------------+
// +---------------------------------------------------------------------+
// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group |
// +---------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | that is bundled with this package in the file LICENSE, and is |
// | available at through the world-wide-web at |
// | http://www.php.net/license/2_02.txt. |
// | If you did not receive a copy of the PHP license and are unable to |
// | obtain it through the world-wide-web, please send a note to |
// | license@php.net so we can mail you a copy immediately. |
// +---------------------------------------------------------------------+
// | Author: Bertrand Mansion <bmansion@mamasam.com> |
// +---------------------------------------------------------------------+
// $Id: Container.php 306597 2010-12-24 05:11:09Z aharvey $
require_once 'Config.php';
* Interface for Config containers
* @author Bertrand Mansion <bmansion@mamasam.com>
* Ex: section, directive, comment, blank
* Container object content
* Container object children
* Reference to container object's parent
* Array of attributes for this item
* Unique id to differenciate nodes
* This is used to compare nodes
* Will not be needed anymore when this class will use ZendEngine 2
* @param string $type Type of container object
* @param string $name Name of container object
* @param string $content Content of container object
* @param array $attributes Array of attributes for container object
function Config_Container($type = 'section', $name = '', $content = '', $attributes = null )
$this->_id = uniqid($name. $type, true );
* Create a child for this item.
* @param string $type type of item: directive, section, comment, blank...
* @param mixed $item item name
* @param string $content item content
* @param array $attributes item attributes
* @param string $where choose a position 'bottom', 'top', 'after', 'before'
* @param object $target needed if you choose 'before' or 'after' for where
* @return object reference to new item or Pear_Error
function &createItem($type, $name, $content, $attributes = null , $where = 'bottom', $target = null )
$result = & $this->addItem($item, $where, $target);
} // end func &createItem
* Adds an item to this item.
* @param object $item a container object
* @param string $where choose a position 'bottom', 'top', 'after', 'before'
* @param object $target needed if you choose 'before' or 'after' in $where
* @return mixed reference to added container on success, Pear_Error on error
function &addItem(&$item, $where = 'bottom', $target = null )
if ($this->type != 'section') {
return PEAR ::raiseError ('Config_Container::addItem must be called on a section type object.', null , PEAR_ERROR_RETURN );
return PEAR ::raiseError ('Target must be a Config_Container object in Config_Container::addItem.', null , PEAR_ERROR_RETURN );
$index = $target->getItemIndex ();
$index = $target->getItemIndex ()+1;
return PEAR ::raiseError ('Use only top, bottom, before or after in Config_Container::addItem.', null , PEAR_ERROR_RETURN );
if (isset ($index) && $index >= 0 ) {
$this->children[$index]->parent = & $this;
* Adds a comment to this item.
* This is a helper method that calls createItem
* @param string $content Object content
* @param string $where Position : 'top', 'bottom', 'before', 'after'
* @param object $target Needed when $where is 'before' or 'after'
* @return object reference to new item or Pear_Error
function &createComment($content = '', $where = 'bottom', $target = null )
return $this->createItem('comment', null , $content, null , $where, $target);
} // end func &createComment
* Adds a blank line to this item.
* This is a helper method that calls createItem
* @return object reference to new item or Pear_Error
function &createBlank($where = 'bottom', $target = null )
return $this->createItem('blank', null , null , null , $where, $target);
} // end func &createBlank
* Adds a directive to this item.
* This is a helper method that calls createItem
* @param string $name Name of new directive
* @param string $content Content of new directive
* @param mixed $attributes Directive attributes
* @param string $where Position : 'top', 'bottom', 'before', 'after'
* @param object $target Needed when $where is 'before' or 'after'
* @return object reference to new item or Pear_Error
function &createDirective($name, $content, $attributes = null , $where = 'bottom', $target = null )
return $this->createItem('directive', $name, $content, $attributes, $where, $target);
} // end func &createDirective
* Adds a section to this item.
* This is a helper method that calls createItem
* If the section already exists, it won't create a new one.
* It will return reference to existing item.
* @param string $name Name of new section
* @param array $attributes Section attributes
* @param string $where Position : 'top', 'bottom', 'before', 'after'
* @param object $target Needed when $where is 'before' or 'after'
* @return object reference to new item or Pear_Error
function &createSection($name, $attributes = null , $where = 'bottom', $target = null )
return $this->createItem('section', $name, null , $attributes, $where, $target);
} // end func &createSection
* Tries to find the specified item(s) and returns the objects.
* $directives =& $obj->getItem('directive');
* $directive_bar_4 =& $obj->getItem('directive', 'bar', null, 4);
* $section_foo =& $obj->getItem('section', 'foo');
* This method can only be called on an object of type 'section'.
* Note that root is a section.
* This method is not recursive and tries to keep the current structure.
* For a deeper search, use searchPath()
* @param string $type Type of item: directive, section, comment, blank...
* @param mixed $name Item name
* @param mixed $content Find item with this content
* @param array $attributes Find item with attribute set to the given value
* @param int $index Index of the item in the returned object list. If it is not set, will try to return the last item with this name.
* @return mixed reference to item found or false when not found
function &getItem($type = null , $name = null , $content = null , $attributes = null , $index = -1 )
if ($this->type != 'section') {
return PEAR ::raiseError ('Config_Container::getItem must be called on a section type object.', null , PEAR_ERROR_RETURN );
$testFields[] = 'content';
$testFields[] = 'attributes';
$fieldsToMatch = count($testFields);
for ($i = 0 , $count = count($this->children); $i < $count; $i++ ) {
foreach ($testFields as $field) {
if ($field != 'attributes') {
if ($this->children[$i]->$field == $ {$field}) {
// Look for attributes in array
$attrToMatch = count($attributes);
foreach ($attributes as $key => $value) {
if (isset ($this->children[$i]->attributes [$key]) &&
$this->children[$i]->attributes [$key] == $value) {
if ($attrMatch == $attrToMatch) {
if ($match == $fieldsToMatch) {
if (isset ($itemsArr[$index])) {
return $itemsArr[$index];
if ($count = count($itemsArr)) {
return $itemsArr[$count-1 ];
* Finds a node using XPATH like format.
* The search format is an array:
* array(item1, item2, item3, ...)
* Each item can be defined as the following:
* item = 'string' : will match the container named 'string'
* item = array('string', array('name' => 'xyz'))
* will match the container name 'string' whose attribute name is equal to "xyz"
* For example : <string name="xyz">
* @param mixed Search path and attributes
* @return mixed Config_Container object, array of Config_Container objects or false on failure.
if ($this->type != 'section') {
return PEAR ::raiseError ('Config_Container::searchPath must be called on a section type object.', null , PEAR_ERROR_RETURN );
// find all the matches for first..
$match = & $this->getItem(null , $name, null , $attributes);
return $match->searchPath ($args);
} // end func &searchPath
* Return a child directive's content.
* This method can use two different search approach, depending on
* the parameter it is given. If the parameter is an array, it will use
* the {@link Config_Container::searchPath()} method. If it is a string,
* it will use the {@link Config_Container::getItem()} method.
* require_once 'Config.php';
* $conf =& $ini->parseConfig('/path/to/config.ini', 'inicommented');
* // Will return the value found at :
* echo $conf->directiveContent(array('Database', 'host')));
* // Will return the value found at :
* echo $conf->directiveContent('date');
* @param mixed Search path and attributes or a directive name
* @param int Index of the item in the returned directive list.
* Eventually used if args is a string.
* @return mixed Content of directive or false if not found.
$item = & $this->getItem('directive', $args, null , null , $index);
return $item->getContent ();
} // end func getDirectiveContent
* Returns how many children this container has
* @param string $type type of children counted
* @param string $name name of children counted
* @return int number of children found
if (isset ($name) && isset ($type)) {
for ($i = 0 , $children = count($this->children); $i < $children; $i++ ) {
if ($this->children[$i]->name === $name &&
for ($i = 0 , $children = count($this->children); $i < $children; $i++ ) {
if ($this->children[$i]->type == $type) {
// Some directives can have the same name
for ($i = 0 , $children = count($this->children); $i < $children; $i++ ) {
if ($this->children[$i]->name === $name) {
} // end func &countChildren
* Deletes an item (section, directive, comment...) from the current object
* TODO: recursive remove in sub-sections
* @return mixed true if object was removed, false if not, or PEAR_Error if root
return PEAR ::raiseError ('Cannot remove root item in Config_Container::removeItem.', null , PEAR_ERROR_RETURN );
* Returns the item index in its parent children array.
* @return int returns int or null if root object
// This will be optimized with Zend Engine 2
$pchildren = & $this->parent->children;
for ($i = 0 , $count = count($pchildren); $i < $count; $i++ ) {
if ($pchildren[$i]->_id == $this->_id) {
} // end func getItemIndex
* Returns the item rank in its parent children array
* according to other items with same type and name.
* @param bool count items differently by type
* @return int returns int or null if root object
$pchildren = & $this->parent->children;
for ($i = 0 , $count = count($pchildren); $i < $count; $i++ ) {
if ($pchildren[$i]->name == $this->name) {
if ($pchildren[$i]->type == $this->type) {
$obj[] = & $pchildren[$i];
$obj[] = & $pchildren[$i];
for ($i = 0 , $count = count($obj); $i < $count; $i++ ) {
if ($obj[$i]->_id == $this->_id) {
} // end func getItemPosition
* Returns the item parent object.
* @return object returns reference to parent object or null if root object
* Returns the item parent object.
* @return mixed returns reference to child object or false if child does not exist
* @return string item's name
* Set this item's content.
* Get this item's content.
* @return string item's content
* @return string item's type
* Set this item's attributes.
* @param array $attributes Array of attributes
} // end func setAttributes
* Set this item's attributes.
* @param array $attributes Array of attributes
foreach ($attributes as $key => $value) {
} // end func updateAttributes
* Get this item's attributes.
* @return array item's attributes
} // end func getAttributes
* Get one attribute value of this item
* @param string $attribute Attribute key
* @return mixed item's attribute value
} // end func getAttribute
* Set a children directive content.
* This is an helper method calling getItem and addItem or setContent for you.
* If the directive does not exist, it will be created at the bottom.
* @param string $name Name of the directive to look for
* @param mixed $content New content
* @param int $index Index of the directive to set,
* in case there are more than one directive
* @return object newly set directive
$item = & $this->getItem('directive', $name, null , null , $index);
if ($item === false || PEAR ::isError ($item)) {
// Directive does not exist, will create one
// Change existing directive value
$item->setContent ($content);
} // end func setDirective
* Is this item root, in a config container object
* @return bool true if item is root
* Call the toString methods in the container plugin
* @param string $configType Type of configuration used to generate the string
* @param array $options Specify special options used by the parser
* @return mixed true on success or PEAR_ERROR
function toString($configType, $options = array ())
if (!isset ($GLOBALS['CONFIG_TYPES'][$configType])) {
return PEAR ::raiseError (" Configuration type '$configType' is not registered in Config_Container::toString." , null , PEAR_ERROR_RETURN );
$includeFile = $GLOBALS['CONFIG_TYPES'][$configType][0 ];
$className = $GLOBALS['CONFIG_TYPES'][$configType][1 ];
include_once($includeFile);
$renderer = new $className($options);
return $renderer->toString ($this);
* Returns a key/value pair array of the container and its children.
* Format : section[directive][index] = value
* If the container has attributes, it will use '@' and '#'
* index is here because multiple directives can have the same name.
* @param bool $useAttr Whether to return the attributes too
$array[$this->name] = array ();
for ($i = 0; $i < $count; $i++ ) {
$newArr = $this->children[$i]->toArray ($useAttr);
foreach ($newArr as $key => $value) {
if (isset ($array[$this->name][$key])) {
!isset ($array[$this->name][$key][0 ])) {
$old = $array[$this->name][$key];
unset ($array[$this->name][$key]);
$array[$this->name][$key][0 ] = $old;
$array[$this->name][$key][] = $value;
$array[$this->name][$key] = $value;
* Writes the configuration to a file
* @param mixed $datasrc Info on datasource such as path to the configuraton file or dsn...
* @param string $configType Type of configuration
* @param array $options Options for writer
* @return mixed true on success or PEAR_ERROR
function writeDatasrc($datasrc, $configType, $options = array ())
if (!isset ($GLOBALS['CONFIG_TYPES'][$configType])) {
return PEAR ::raiseError (" Configuration type '$configType' is not registered in Config_Container::writeDatasrc." , null , PEAR_ERROR_RETURN );
$includeFile = $GLOBALS['CONFIG_TYPES'][$configType][0 ];
$className = $GLOBALS['CONFIG_TYPES'][$configType][1 ];
include_once($includeFile);
$writer = new $className($options);
return $writer->writeDatasrc ($datasrc, $this);
$fp = @fopen($datasrc, 'w');
$string = $this->toString($configType, $options);
return PEAR ::raiseError ('Cannot open datasource for writing.', 1 , PEAR_ERROR_RETURN );
} // end func writeDatasrc
} // end class Config_Container
Documentation generated on Mon, 11 Mar 2019 15:42:04 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.
|