Class: I2CE MagicDataNode

This article desrcibes the class I2CE_MagicDataNode.

• Implements the interface RecursiveIterator
• Implements the interface SeekableIterator
• Implements the interface ArrayAccess
• Implements the interface Countable
• Location: Part of the module I2CE in the package I2CE
• Source: Defined in the file lib/I2CE_MagicDataNode.php

Configuration class to lookup and save configuration options.

Constants

I2CE_MagicDataNode::TYPE_NOT_POPULATED

Constant type value when this data set hasn't tried to

populate from storage yet.

Defined as: -2

I2CE_MagicDataNode::TYPE_INDETERMINATE

Constant type value when this data set hasn't been defined. Defined as: -1

I2CE_MagicDataNode::TYPE_PARENT

Constant type value when this data set is a parent node. Defined as: 0

I2CE_MagicDataNode::TYPE_STRING_VALUE

Constant type value when this data set is a string value. Defined as: 1

Variables

$type

The type of this configuration setting. Possible values are -1 = unset, 0 = parent object, 1 = scalar/value.

• Type: protected nteger $type

$name

The name of this configuration setting.

• Type: protected ng $name

$value

The value of this configuration setting. This is only valid when type = 1.

• Type: protected ng $value

$children

All children configuration objects for this configuration group. This is only valid when type = 0

• Type: protected y $children

$parent

The parent of this configuration.

• Type: protected I2CE_MagicDataNode $parent

$parentPath

• Type: protected $parentPath

$parentPathTop

• Type: protected $parentPathTop

$top

The top level of this configuration.

• Type: protected I2CE_MagicDataNode $top

$volatile

. True if the data is volatile. Defaults to false

• Type: protected n $volatile

$attributes

• Type: protected $attributes

Methods

__construct()

Construct a new configuration value or grouping.

• Signature: protected function __construct($name,$parent,$check_key)

Parameters:

• string $name
  The name of this configuration setting.
  • Default Value: null
• I2CE_MagicDataNode $parent
  The parent of this configuration setting.
  • Default Value: null
• boolean $check_key
  Defaults to true in which case we check that the key is valid.
  • Default Value: true

__get()

Get the value for a child configuration option.

• Signature: public function __get($path)
• Returns: mixed. Null if the path was

invalid. I2CE_MagicDataNode or string on success Parameters:

• $path

__isset()

Check to see if a given key or path exists and the value is set

returns mixed. Booolean true or false if the magic data referenced by the given path is set. null on failure (invalid path)

• Signature: public function __isset($path)

Parameters:

• mixed $path
  {@see traverse()}

__set()

Set the value for a child configuration option.

• Signature: public function __set($path,$value)

Parameters:

• mixed $path
  {@see traverse()}
• mixed $value

__toString()

• Signature: public function __toString()

__unset()

Unset a given key in the children array.

• Signature: final public function __unset($key)

Parameters:

• string $key

_getAsArray()

• Signature: protected function _getAsArray($locale)

Parameters:

• string $locale
  The locale we wish to get the values for. Defaults to null meaning we are not getting tranlsated values.
  • Default Value: null

_getAttribute()

• Signature: protected function _getAttribute($key,$prefix)

Parameters:

• $key
• $prefix

_getAttributes()

• Signature: protected function _getAttributes($keys_only,$prefix)

Parameters:

• $keys_only
• $prefix

_hasAttribute()

• Signature: protected function _hasAttribute($key,$prefix)

Parameters:

• $key
• $prefix

_removeAttribute()

• Signature: protected function _removeAttribute($prefix,$key)

Parameters:

• $prefix
• $key

_setAttribute()

• Signature: protected function _setAttribute($key,$val,$prefix)

Parameters:

• $key
• $val
• $prefix

checkKey()

Check to make sure a given key is valid. It can be any combination of _-+.0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

• Signature: static public function checkKey($key)
• Returns: boolean

Parameters:

• string $key

count()

• Signature: public function count()

current()

• Signature: public function current()

erase()

Erases the current node and all of its subnodes from the storage mechanism.

• Signature: public function erase($locale)
• Returns: boolean true on success

Parameters:

• string $locale
  The locale we wish to erase the values for. Defaults to null meaning we erase all values/locales
  • Default Value: null

eraseChildren()

Erases all children of the current node and all of its subnodes from the storage mechanism.

values for. Defaults to null meaning we erase all values/locales

• Signature: public function eraseChildren($locale)
• Returns: boolean true on success

Parameters:

• string $locale
  The locale we wish to erase the
  • Default Value: null

getAsArray()

Return an array of all the child values for this object.

• Signature: public function getAsArray($path,$locale)
• Returns: array

Parameters:

• mixed $path
  {@see traverse()}. Defaults to null which means we get at this node
  • Default Value: null
• string $locale
  The locale we wish to get the values for. Defaults to null meaning we are not getting tranlsated values.
  • Default Value: null

getAttribute()

Gets an attribute

• Signature: public function getAttribute($key)
• Returns: mixed string if the attribute value. null if it does not exist.

Parameters:

• string $key

getAttributes()

Get the attributes If true returns associative array of attribute=>value pairs

• Signature: public function getAttributes($keys_only)
• Returns: array

Parameters:

• boolean $keys_only
  Defaults to false. If true returns only the attribute names that are set.
  • Default Value: false

getChildren()

• Signature: public function getChildren()

getKeys()

Return an array of all child keys for this object.

• Signature: public function getKeys($path,$attrs)
• Returns: array

Parameters:

• mixed $path
  {@see traverse()}
  • Default Value: null
• $attrs
  • Default Value: false

getName()

Return the name of this configuration setting.

• Signature: public function getName()
• Returns: string

getParent()

Get the parent magic data node

• Signature: public function getParent()
• Returns: I2CE_MagicDataNode

getPath()

Return the full path to this configuration setting.

• Signature: public function getPath($show_top)
• Returns: string

Parameters:

• boolean $show_top
  defaults to true if we are to show the parent
  • Default Value: true

getSaveValue()

Return the direct scalar value for this node.

• Signature: public function getSaveValue()
• Returns: string

getTranslation()

• Signature: public function getTranslation($locale,$resolve,$path)

Parameters:

• $locale
• $resolve
  • Default Value: true
• $path
  • Default Value: null

getTranslations()

Get the translations for the current node If true returns associative array of locale=>translation pairs

• Signature: public function getTranslations($locales_only,$include_default_locale)
• Returns: array

Parameters:

• boolean $locales_only
  Defaults to false. If true returns only the loclaes for which a translation exists
  • Default Value: false
• boolean $include_default_locale
  Defaults to true in which case we include the nodes values under the default locale
  • Default Value: true

getType()

Return the type of this node.

• Signature: public function getType()
• Returns: int or false on failure

getValue()

Return the value of this configuration object if the type == 1 and the current object if type is anything else.

• Signature: public function getValue()
• Returns: mixed

hasAttribute()

Checks to see if an attribute is present

• Signature: public function hasAttribute($key)
• Returns: mixed boolean. true if key exists, false if it does not, null if an invalid key

Parameters:

• string $key

hasChildren()

whether the current key has children or not. this is _not_ whether this has a children or not

• Signature: public function hasChildren()

isScalar()

• Signature: private function isScalar()

is_indeterminate()

Check to see if the value at the specified path is indeterminate @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: public function is_indeterminate($path)
• Returns: boolean. True if it is a scalar value

Parameters:

• $path
  • Default Value: null

is_parent()

Check to see if the value at the specified path is set and is a parent node. @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: public function is_parent($path)
• Returns: boolean. True if it is a scalar value

Parameters:

• $path
  • Default Value: null

is_populated()

Check to see if the value at the specified path is populated @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: protected function is_populated($path)
• Returns: boolean. True if it is a scalar value

Parameters:

• $path
  • Default Value: null

is_root()

• Signature: public function is_root($path)

Parameters:

• $path
  • Default Value: null

is_scalar()

Check to see if the value at the specified path is set and is a scalar. @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: public function is_scalar($path)
• Returns: boolean. True if it is a scalar value

Parameters:

• $path
  • Default Value: null

is_translatable()

Checked to see if the node referenced is translatable

• Signature: public function is_translatable($path)
• Returns: boolean.

Parameters:

• string $path
  Defaults to null, meaning the current node.
  • Default Value: null

is_translated()

Checked to see if the node referenced is translated ito the given locale

• Signature: public function is_translated($locale,$path)
• Returns: boolean.

Parameters:

• string $locale
• string $path
  Defaults to null, meaning the current node.
  • Default Value: null

key()

• Signature: public function key()

krsort()

• Signature: public function krsort($sort_flags,$recurse)

Parameters:

• $sort_flags
  • Default Value: SORT_REGULAR
• $recurse
  • Default Value: false

ksort()

• Signature: public function ksort($sort_flags,$recurse)

Parameters:

• $sort_flags
  • Default Value: SORT_REGULAR
• $recurse
  • Default Value: false

newAttribute()

Make a new attribute this object with the given key. The $nosave flag should only be set when populating a parent node from storage.

• Signature: protected function newAttribute($key,$save,$prefix)
• Returns: mixed. false on failure, the attribute created on succes

Parameters:

• scalar $key
  the key
• boolean $save
  Set to true to not save the parent and attribute
• $prefix

newChild()

Make a new child for this object with the given key. The $nosave flag should only be set when populating a parent node from storage.

end of the array. Otherwise we use the given key as a key.

after creating this child.

• Signature: protected function newChild($key,$save)
• Returns: I2CE_MagicDataNode The child that was created or

null on failure Parameters:

• scalar $key
  If a boolean and true, we add to the
• boolean $save
  Set to true to not save the parent
  • Default Value: TRUE

next()

• Signature: public function next()

offsetExists()

• Signature: public function offsetExists($key)

Parameters:

• $key

offsetGet()

• Signature: public function offsetGet($key)

Parameters:

• $key

offsetSet()

• Signature: public function offsetSet($key,$val)

Parameters:

• $key
• $val

offsetUnset()

• Signature: public function offsetUnset($key)

Parameters:

• $key

pathDivider()

Return the path divider for this MagicDataNode object

• Signature: protected function pathDivider()
• Returns: string

pathExists()

Check to see if a given key key or path exists

returns mixed. Booolean true or false if the magic data referenced by the given path is set. null on failure (invalid path)

• Signature: public function pathExists($path)

Parameters:

• mixed $path
  {@see traverse()}

pop()

Pop a value off the end of a parent/indeterminate node. @param mixed. Scalar value if the node is scalar, an array if it is a parent, otherwise null.

• Signature: public function pop()

populate()

Populate any stored data based on the storage objects set in the top node.

• Signature: protected function populate()
• Returns: true on success.

push()

Push a value onto the end of a parent/indeterminate node.

• Signature: public function push($val)
• Returns: int the number of children the current node has. null on failure

Parameters:

• mixed $val
  ;

raiseError()

Raise an error and redirect the user for any critical errors.

The default redirect will go to the home page for the site. @param string/mixed $message The error message. @global array

• Signature: static public function raiseError($message,$type,$redirect)

Parameters:

• $message
• integer $type
  The error type.
  • Default Value: E_USER_NOTICE
• string $redirect
  The page to redirect to for critical errors.
  • Default Value: ""

removeAttribute()

Removes an attribute

• Signature: public function removeAttribute($key)
• Returns: true if the attribute was removed. false if the attribute did not exist

Parameters:

• string $key

removeTranslation()

• Signature: public function removeTranslation($locale)

Parameters:

• $locale

rewind()

• Signature: public function rewind()

save()

Call all the storage methods associated with this configuration. of this node as well.

• Signature: protected function save($recurse)

Parameters:

• boolean $recurse
  Defaults to false. If true, and we were able to succesfully save this node, we recrusively save all the populated children
  • Default Value: false

setAttribute()

• Signature: public function setAttribute($key,$val)

Parameters:

• $key
• $val

setIfIsSet()

If the data referenced by that path is set, we set the value of $data to that data magic data referenced by $path. If false then we only set $data if the magic data node refrenced by $path is a leaf node/value

• Signature: public function setIfIsSet($data,$path,$as_array)
• Returns: boolean. true if the value was set

Parameters:

• mixed &$data
  where you wish to store the magic data if it is set
• mixed $path
  {@see traverse()}. Defaults to null which means we get at this node
• boolean $as_array
  defaults to false. If true, will set $data to be the result of calling getAsArray() on the
  • Default Value: false

setTranslatable()

Sets the translatable attribute for the referenced node @param boolean $transtable. Defaults to true

• Signature: public function setTranslatable($path,$translatable)
• Returns: true on success, false on failure

Parameters:

• string $path
  Defaults to null, meaning the current node
  • Default Value: null
• $translatable
  • Default Value: true

setTranslation()

• Signature: public function setTranslation($locale,$translation,$path)

Parameters:

• $locale
• $translation
• $path
  • Default Value: null

setType()

Set the type for this object. The nosave flag should be set to true if the calling function is going to save so that it doesn't get saved twice.

• Signature: protected function setType($type)
• Returns: boolean true on success

Parameters:

• integer $type

setValue()

Set the scalar value for this object.

• Signature: public function setValue($value,$locale,$set_default_locale)
• Returns: true on sucess

Parameters:

• mixed $value
• string $locale
  The locale we wish to set the value for. Defaults to null meaning we are not setting tranlsated values.
  • Default Value: null
• boolean $set_default_locale
  Defautls to true. When setting values, make sure the default locale is set.
  • Default Value: true

set_parent()

Set the magic data node at the specified path to be a parent node if is indeterminate @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: public function set_parent($path)
• Returns: boolean. True on success

Parameters:

• $path
  • Default Value: null

set_scalar()

Set the magic data node at the specified path to be scalar if is indeterminate @param strign $key. A key or path in the magic data. If null (default) then we are checking on the node itself

• Signature: public function set_scalar($path)
• Returns: boolean. True on success

Parameters:

• $path
  • Default Value: null

traverse()

Traverse magic data by a given path

e.g. array('some','magic','data','path). There are three special path components, , '.' and '..' The first two mean don't go anywhere, while the third means go to the parent node. return null if the path is not already set.

• Signature: public function traverse($path,$create,$return_value)
• Returns: mixed. String, if the path is valid and refers to a leaf node.

I2CE_MagicDataNode if the path is valid but not a leaf node, or null on ffailure (invalid path/path not set) Parameters:

• array $path
  A string which is a path e.g. '/some/magic/data/path' or an array of path components
• boolean $create
  Defaults to false. If true, it will create the magic data path as it goes. If false, it will
  • Default Value: false
• boolean $return_value
  Defaults to true. If true returns the value of of a leaf node rather than the node itself
  • Default Value: true

uksort()

• Signature: public function uksort($cmp_function,$recurse)

Parameters:

• $cmp_function
• $recurse
  • Default Value: false

unpopulate()

• Signature: public function unpopulate($deep)

Parameters:

• $deep
  • Default Value: true

valid()

• Signature: public function valid()

volatile()

Check/set whether this magic data is volatile or not

this node (does not apply to subnodes). If not set we return the volatility state of this node. Defaults to not set (null). Recursively sets all sub-nodes to volatile.

• Signature: public function volatile($volatile)
• Returns: mixed

Parameters:

• boolean $volatile
  If set, we set the volatility of
  • Default Value: null