set.php

Aller à la documentation de ce fichier.

<?php
/**
 * @package     Joomla.Platform
 * @subpackage  Data
 *
 * @copyright   Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE
 */

defined('JPATH_PLATFORM') or die;

/**
 * JDataSet is a collection class that allows the developer to operate on a set of JData objects as if they were in a
 * typical PHP array.
 *
 * @package     Joomla.Platform
 * @subpackage  Data
 * @since       12.3
 */
class JDataSet implements JDataDumpable, ArrayAccess, Countable, Iterator
{
        /**
         * The current position of the iterator.
         *
         * @var    integer
         * @since  12.3
         */
        private $_current = false;

        /**
         * The iterator objects.
         *
         * @var    array
         * @since  12.3
         */
        private $_objects = array();

        /**
         * The class constructor.
         *
         * @param   array  $objects  An array of JData objects to bind to the data set.
         *
         * @since   12.3
         * @throws  InvalidArgumentException if an object is not an instance of JData.
         */
        public function __construct(array $objects = array())
        {
                // Set the objects.
                $this->_initialise($objects);
        }

        /**
         * The magic call method is used to call object methods using the iterator.
         *
         * Example: $array = $objectList->foo('bar');
         *
         * The object list will iterate over its objects and see if each object has a callable 'foo' method.
         * If so, it will pass the argument list and assemble any return values. If an object does not have
         * a callable method no return value is recorded.
         * The keys of the objects and the result array are maintained.
         *
         * @param   string  $method     The name of the method called.
         * @param   array   $arguments  The arguments of the method called.
         *
         * @return  array   An array of values returned by the methods called on the objects in the data set.
         *
         * @since   12.3
         */
        public function __call($method, $arguments = array())
        {
                $return = array();

                // Iterate through the objects.
                foreach ($this->_objects as $key => $object)
                {
                        // Create the object callback.
                        $callback = array($object, $method);

                        // Check if the callback is callable.
                        if (is_callable($callback))
                        {
                                // Call the method for the object.
                                $return[$key] = call_user_func_array($callback, $arguments);
                        }
                }

                return $return;
        }

        /**
         * The magic get method is used to get a list of properties from the objects in the data set.
         *
         * Example: $array = $dataSet->foo;
         *
         * This will return a column of the values of the 'foo' property in all the objects
         * (or values determined by custom property setters in the individual JData's).
         * The result array will contain an entry for each object in the list (compared to __call which may not).
         * The keys of the objects and the result array are maintained.
         *
         * @param   string  $property  The name of the data property.
         *
         * @return  array  An associative array of the values.
         *
         * @since   12.3
         */
        public function __get($property)
        {
                $return = array();

                // Iterate through the objects.
                foreach ($this->_objects as $key => $object)
                {
                        // Get the property.
                        $return[$key] = $object->$property;
                }

                return $return;
        }

        /**
         * The magic isset method is used to check the state of an object property using the iterator.
         *
         * Example: $array = isset($objectList->foo);
         *
         * @param   string  $property  The name of the property.
         *
         * @return  boolean  True if the property is set in any of the objects in the data set.
         *
         * @since   12.3
         */
        public function __isset($property)
        {
                $return = array();

                // Iterate through the objects.
                foreach ($this->_objects as $object)
                {
                        // Check the property.
                        $return[] = isset($object->$property);
                }

                return in_array(true, $return, true) ? true : false;
        }

        /**
         * The magic set method is used to set an object property using the iterator.
         *
         * Example: $objectList->foo = 'bar';
         *
         * This will set the 'foo' property to 'bar' in all of the objects
         * (or a value determined by custom property setters in the JData).
         *
         * @param   string  $property  The name of the property.
         * @param   mixed   $value     The value to give the data property.
         *
         * @return  void
         *
         * @since   12.3
         */
        public function __set($property, $value)
        {
                // Iterate through the objects.
                foreach ($this->_objects as $object)
                {
                        // Set the property.
                        $object->$property = $value;
                }
        }

        /**
         * The magic unset method is used to unset an object property using the iterator.
         *
         * Example: unset($objectList->foo);
         *
         * This will unset all of the 'foo' properties in the list of JData's.
         *
         * @param   string  $property  The name of the property.
         *
         * @return  void
         *
         * @since   12.3
         */
        public function __unset($property)
        {
                // Iterate through the objects.
                foreach ($this->_objects as $object)
                {
                        unset($object->$property);
                }
        }

        /**
         * Gets the number of data objects in the set.
         *
         * @return  integer  The number of objects.
         *
         * @since   12.3
         */
        public function count()
        {
                return count($this->_objects);
        }

        /**
         * Clears the objects in the data set.
         *
         * @return  JDataSet  Returns itself to allow chaining.
         *
         * @since   12.3
         */
        public function clear()
        {
                $this->_objects = array();
                $this->rewind();

                return $this;
        }

        /**
         * Get the current data object in the set.
         *
         * @return  JData  The current object, or false if the array is empty or the pointer is beyond the end of the elements.
         *
         * @since   12.3
         */
        public function current()
        {
                return is_scalar($this->_current) ? $this->_objects[$this->_current] : false;
        }

        /**
         * Dumps the data object in the set, recursively if appropriate.
         *
         * @param   integer           $depth   The maximum depth of recursion (default = 3).
         *                                     For example, a depth of 0 will return a stdClass with all the properties in native
         *                                     form. A depth of 1 will recurse into the first level of properties only.
         * @param   SplObjectStorage  $dumped  An array of already serialized objects that is used to avoid infinite loops.
         *
         * @return  array  An associative array of the date objects in the set, dumped as a simple PHP stdClass object.
         *
         * @see     JData::dump()
         * @since   12.3
         */
        public function dump($depth = 3, SplObjectStorage $dumped = null)
        {
                // Check if we should initialise the recursion tracker.
                if ($dumped === null)
                {
                        $dumped = new SplObjectStorage;
                }

                // Add this object to the dumped stack.
                $dumped->attach($this);

                $objects = array();

                // Make sure that we have not reached our maximum depth.
                if ($depth > 0)
                {
                        // Handle JSON serialization recursively.
                        foreach ($this->_objects as $key => $object)
                        {
                                $objects[$key] = $object->dump($depth, $dumped);
                        }
                }

                return $objects;
        }

        /**
         * Gets the data set in a form that can be serialised to JSON format.
         *
         * Note that this method will not return an associative array, otherwise it would be encoded into an object.
         * JSON decoders do not consistently maintain the order of associative keys, whereas they do maintain the order of arrays.
         *
         * @param   mixed  $serialized  An array of objects that have already been serialized that is used to infinite loops
         *                              (null on first call).
         *
         * @return  array  An array that can be serialised by json_encode().
         *
         * @since   12.3
         */
        public function jsonSerialize($serialized = null)
        {
                // Check if we should initialise the recursion tracker.
                if ($serialized === null)
                {
                        $serialized = array();
                }

                // Add this object to the serialized stack.
                $serialized[] = spl_object_hash($this);
                $return = array();

                // Iterate through the objects.
                foreach ($this->_objects as $object)
                {
                        // Call the method for the object.
                        $return[] = $object->jsonSerialize($serialized);
                }

                return $return;
        }

        /**
         * Gets the key of the current object in the iterator.
         *
         * @return  scalar  The object key on success; null on failure.
         *
         * @since   12.3
         */
        public function key()
        {
                return $this->_current;
        }

        /**
         * Gets the array of keys for all the objects in the iterator (emulates array_keys).
         *
         * @return  array  The array of keys
         *
         * @since   12.3
         */
        public function keys()
        {
                return array_keys($this->_objects);
        }

        /**
         * Advances the iterator to the next object in the iterator.
         *
         * @return  void
         *
         * @since   12.3
         */
        public function next()
        {
                // Get the object offsets.
                $keys = $this->keys();

                // Check if _current has been set to false but offsetUnset.
                if ($this->_current === false && isset($keys[0]))
                {
                        // This is a special case where offsetUnset was used in a foreach loop and the first element was unset.
                        $this->_current = $keys[0];
                }
                else
                {
                        // Get the current key.
                        $position = array_search($this->_current, $keys);

                        // Check if there is an object after the current object.
                        if ($position !== false && isset($keys[$position + 1]))
                        {
                                // Get the next id.
                                $this->_current = $keys[$position + 1];
                        }
                        else
                        {
                                // That was the last object or the internal properties have become corrupted.
                                $this->_current = null;
                        }
                }
        }

        /**
         * Checks whether an offset exists in the iterator.
         *
         * @param   mixed  $offset  The object offset.
         *
         * @return  boolean  True if the object exists, false otherwise.
         *
         * @since   12.3
         */
        public function offsetExists($offset)
        {
                return isset($this->_objects[$offset]);
        }

        /**
         * Gets an offset in the iterator.
         *
         * @param   mixed  $offset  The object offset.
         *
         * @return  JData  The object if it exists, null otherwise.
         *
         * @since   12.3
         */
        public function offsetGet($offset)
        {
                return isset($this->_objects[$offset]) ? $this->_objects[$offset] : null;
        }

        /**
         * Sets an offset in the iterator.
         *
         * @param   mixed  $offset  The object offset.
         * @param   JData  $object  The object object.
         *
         * @return  void
         *
         * @since   12.3
         * @throws  InvalidArgumentException if an object is not an instance of JData.
         */
        public function offsetSet($offset, $object)
        {
                // Check if the object is a JData object.
                if (!($object instanceof JData))
                {
                        throw new InvalidArgumentException(sprintf('%s("%s", *%s*)', __METHOD__, $offset, gettype($object)));
                }

                // Set the offset.
                $this->_objects[$offset] = $object;
        }

        /**
         * Unsets an offset in the iterator.
         *
         * @param   mixed  $offset  The object offset.
         *
         * @return  void
         *
         * @since   12.3
         */
        public function offsetUnset($offset)
        {
                if (!$this->offsetExists($offset))
                {
                        // Do nothing if the offset does not exist.
                        return;
                }

                // Check for special handling of unsetting the current position.
                if ($offset == $this->_current)
                {
                        // Get the current position.
                        $keys = $this->keys();
                        $position = array_search($this->_current, $keys);

                        // Check if there is an object before the current object.
                        if ($position > 0)
                        {
                                // Move the current position back one.
                                $this->_current = $keys[$position - 1];
                        }
                        else
                        {
                                // We are at the start of the keys AND let's assume we are in a foreach loop and `next` is going to be called.
                                $this->_current = false;
                        }
                }

                unset($this->_objects[$offset]);
        }

        /**
         * Rewinds the iterator to the first object.
         *
         * @return  void
         *
         * @since   12.3
         */
        public function rewind()
        {
                // Set the current position to the first object.
                if (empty($this->_objects))
                {
                        $this->_current = false;
                }
                else
                {
                        $keys = $this->keys();
                        $this->_current = array_shift($keys);
                }
        }

        /**
         * Validates the iterator.
         *
         * @return  boolean  True if valid, false otherwise.
         *
         * @since   12.3
         */
        public function valid()
        {
                // Check the current position.
                if (!is_scalar($this->_current) || !isset($this->_objects[$this->_current]))
                {
                        return false;
                }

                return true;
        }

        /**
         * Initialises the list with an array of objects.
         *
         * @param   array  $input  An array of objects.
         *
         * @return  void
         *
         * @since   12.3
         * @throws  InvalidArgumentException if an object is not an instance of JData.
         */
        private function _initialise(array $input = array())
        {
                foreach ($input as $key => $object)
                {
                        if (!is_null($object))
                        {
                                $this->offsetSet($key, $object);
                        }
                }

                $this->rewind();
        }
}