primo commit

libraries/vendor/joomla/data/src/DataObject.php

@@ -0,0 +1,311 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Data Package
+ *
+ * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Data;
+
+use Joomla\Registry\Registry;
+
+/**
+ * DataObject is a class that is used to store data but allowing you to access the data by mimicking the way PHP handles class properties.
+ *
+ * @since  1.0
+ */
+class DataObject implements DumpableInterface, \IteratorAggregate, \JsonSerializable, \Countable
+{
+    /**
+     * The data object properties.
+     *
+     * @var    array
+     * @since  1.0
+     */
+    private $properties = [];
+
+    /**
+     * The class constructor.
+     *
+     * @param   mixed  $properties  Either an associative array or another object by which to set the initial properties of the new object.
+     *
+     * @since   1.0
+     * @throws  \InvalidArgumentException
+     */
+    public function __construct($properties = [])
+    {
+        // Check the properties input.
+        if (!empty($properties)) {
+            // Bind the properties.
+            $this->bind($properties);
+        }
+    }
+
+    /**
+     * The magic get method is used to get a data property.
+     *
+     * This method is a public proxy for the protected getProperty method.
+     *
+     * Note: Magic __get does not allow recursive calls. This can be tricky because the error generated by recursing into
+     * __get is "Undefined property:  {CLASS}::{PROPERTY}" which is misleading. This is relevant for this class because
+     * requesting a non-visible property can trigger a call to a sub-function. If that references the property directly in
+     * the object, it will cause a recursion into __get.
+     *
+     * @param   string  $property  The name of the data property.
+     *
+     * @return  mixed  The value of the data property, or null if the data property does not exist.
+     *
+     * @see     DataObject::getProperty()
+     * @since   1.0
+     */
+    public function __get($property)
+    {
+        return $this->getProperty($property);
+    }
+
+    /**
+     * The magic isset method is used to check the state of an object property.
+     *
+     * @param   string  $property  The name of the data property.
+     *
+     * @return  boolean
+     *
+     * @since   1.0
+     */
+    public function __isset($property)
+    {
+        return isset($this->properties[$property]);
+    }
+
+    /**
+     * The magic set method is used to set a data property.
+     *
+     * This is a public proxy for the protected setProperty method.
+     *
+     * @param   string  $property  The name of the data property.
+     * @param   mixed   $value     The value to give the data property.
+     *
+     * @return  void
+     *
+     * @see     DataObject::setProperty()
+     * @since   1.0
+     */
+    public function __set($property, $value)
+    {
+        $this->setProperty($property, $value);
+    }
+
+    /**
+     * The magic unset method is used to unset a data property.
+     *
+     * @param   string  $property  The name of the data property.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     */
+    public function __unset($property)
+    {
+        unset($this->properties[$property]);
+    }
+
+    /**
+     * Binds an array or object to this object.
+     *
+     * @param   mixed    $properties   An associative array of properties or an object.
+     * @param   boolean  $updateNulls  True to bind null values, false to ignore null values.
+     *
+     * @return  $this
+     *
+     * @since   1.0
+     * @throws  \InvalidArgumentException
+     */
+    public function bind($properties, $updateNulls = true)
+    {
+        // Check the properties data type.
+        if (!\is_array($properties) && !\is_object($properties)) {
+            throw new \InvalidArgumentException(
+                sprintf('The $properties argument must be an array or object, a %s was given.', \gettype($properties))
+            );
+        }
+
+        // Check if the object is traversable.
+        if ($properties instanceof \Traversable) {
+            // Convert iterator to array.
+            $properties = iterator_to_array($properties);
+        } elseif (\is_object($properties)) {
+            // Convert properties to an array.
+            $properties = (array) $properties;
+        }
+
+        // Bind the properties.
+        foreach ($properties as $property => $value) {
+            // Check if the value is null and should be bound.
+            if ($value === null && !$updateNulls) {
+                continue;
+            }
+
+            // Set the property.
+            $this->setProperty($property, $value);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Dumps the data properties into an object, 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  \stdClass
+     *
+     * @since   1.0
+     */
+    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);
+
+        // Setup a container.
+        $dump = new \stdClass();
+
+        // Dump all object properties.
+        foreach (array_keys($this->properties) as $property) {
+            // Get the property.
+            $dump->$property = $this->dumpProperty($property, $depth, $dumped);
+        }
+
+        return $dump;
+    }
+
+    /**
+     * Gets this object represented as an ArrayIterator.
+     *
+     * This allows the data properties to be access via a foreach statement.
+     *
+     * @return  \ArrayIterator
+     *
+     * @see     IteratorAggregate::getIterator()
+     * @since   1.0
+     */
+    public function getIterator()
+    {
+        return new \ArrayIterator($this->dump(0));
+    }
+
+    /**
+     * Gets the data properties in a form that can be serialised to JSON format.
+     *
+     * @return  mixed
+     *
+     * @since   1.0
+     */
+    public function jsonSerialize()
+    {
+        return $this->dump();
+    }
+
+    /**
+     * Dumps a data property.
+     *
+     * If recursion is set, this method will dump any object implementing DumpableInterface (like DataObject and DataSet); it will
+     * convert a DateTimeInterface object to a string; and it will convert a Joomla\Registry\Registry to an object.
+     *
+     * @param   string             $property  The name of the data property.
+     * @param   integer            $depth     The current depth of recursion (a value of 0 will ignore recursion).
+     * @param   \SplObjectStorage  $dumped    An array of already serialized objects that is used to avoid infinite loops.
+     *
+     * @return  mixed  The value of the dumped property.
+     *
+     * @since   1.0
+     */
+    protected function dumpProperty($property, $depth, \SplObjectStorage $dumped)
+    {
+        $value = $this->getProperty($property);
+
+        if ($depth > 0) {
+            // Check if the object is also a dumpable object.
+            if ($value instanceof DumpableInterface) {
+                // Do not dump the property if it has already been dumped.
+                if (!$dumped->contains($value)) {
+                    $value = $value->dump($depth - 1, $dumped);
+                }
+            }
+
+            // Check if the object is a date.
+            if ($value instanceof \DateTimeInterface) {
+                $value = $value->format('Y-m-d H:i:s');
+            } elseif ($value instanceof Registry) {
+                $value = $value->toObject();
+            }
+        }
+
+        return $value;
+    }
+
+    /**
+     * Gets a data property.
+     *
+     * @param   string  $property  The name of the data property.
+     *
+     * @return  mixed  The value of the data property.
+     *
+     * @see     DataObject::__get()
+     * @since   1.0
+     */
+    protected function getProperty($property)
+    {
+        return $this->properties[$property] ?? null;
+    }
+
+    /**
+     * Sets a data property.
+     *
+     * If the name of the property starts with a null byte, this method will return null.
+     *
+     * @param   string  $property  The name of the data property.
+     * @param   mixed   $value     The value to give the data property.
+     *
+     * @return  mixed  The value of the data property.
+     *
+     * @see     DataObject::__set()
+     * @since   1.0
+     */
+    protected function setProperty($property, $value)
+    {
+        /*
+         * Check if the property starts with a null byte. If so, discard it because a later attempt to try to access it
+         * can cause a fatal error. See http://www.php.net/manual/en/language.types.array.php#language.types.array.casting
+         */
+        if (strpos($property, "\0") === 0) {
+            return;
+        }
+
+        // Set the value.
+        $this->properties[$property] = $value;
+
+        return $value;
+    }
+
+    /**
+     * Count the number of data properties.
+     *
+     * @return  integer  The number of data properties.
+     *
+     * @since   1.0
+     */
+    public function count()
+    {
+        return \count($this->properties);
+    }
+}

libraries/vendor/joomla/data/src/DataSet.php

@@ -0,0 +1,573 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Data Package
+ *
+ * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Data;
+
+/**
+ * DataSet is a collection class that allows the developer to operate on a set of DataObjects as if they were in a typical PHP array.
+ *
+ * @since  1.0
+ */
+class DataSet implements DumpableInterface, \ArrayAccess, \Countable, \Iterator
+{
+    /**
+     * The current position of the iterator.
+     *
+     * @var    integer
+     * @since  1.0
+     */
+    private $current = false;
+
+    /**
+     * The iterator objects.
+     *
+     * @var    DataObject[]
+     * @since  1.0
+     */
+    private $objects = [];
+
+    /**
+     * The class constructor.
+     *
+     * @param   DataObject[]  $objects  An array of DataObject objects to bind to the data set.
+     *
+     * @since   1.0
+     * @throws  \InvalidArgumentException if an object is not a DataObject.
+     */
+    public function __construct(array $objects = [])
+    {
+        // 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   1.0
+     */
+    public function __call($method, $arguments = [])
+    {
+        $return = [];
+
+        // Iterate through the objects.
+        foreach ($this->objects as $key => $object) {
+            // Create the object callback.
+            $callback = [$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 DataObject'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   1.0
+     */
+    public function __get($property)
+    {
+        $return = [];
+
+        // 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   1.0
+     */
+    public function __isset($property)
+    {
+        $return = [];
+
+        // Iterate through the objects.
+        foreach ($this->objects as $object) {
+            // Check the property.
+            $return[] = isset($object->$property);
+        }
+
+        return \in_array(true, $return, true);
+    }
+
+    /**
+     * 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 DataObject).
+     *
+     * @param   string  $property  The name of the property.
+     * @param   mixed   $value     The value to give the data property.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     */
+    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 DataObject's.
+     *
+     * @param   string  $property  The name of the property.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     */
+    public function __unset($property)
+    {
+        // Iterate through the objects.
+        foreach ($this->objects as $object) {
+            unset($object->$property);
+        }
+    }
+
+    /**
+     * Gets an array of keys, existing in objects
+     *
+     * @param   string  $type  Selection type 'all' or 'common'
+     *
+     * @return  array   Array of keys
+     *
+     * @since   1.2.0
+     * @throws  \InvalidArgumentException
+     */
+    public function getObjectsKeys($type = 'all')
+    {
+        $keys = null;
+
+        if ($type == 'all') {
+            $function = 'array_merge';
+        } elseif ($type == 'common') {
+            $function = 'array_intersect_key';
+        } else {
+            throw new \InvalidArgumentException("Unknown selection type: $type");
+        }
+
+        foreach ($this->objects as $object) {
+            $objectVars = json_decode(json_encode($object), true);
+
+            $keys = ($keys === null) ? $objectVars : $function($keys, $objectVars);
+        }
+
+        return array_keys($keys);
+    }
+
+    /**
+     * Gets all objects as an array
+     *
+     * @param   boolean  $associative  Option to set return mode: associative or numeric array.
+     * @param   string   ...$keys      Unlimited optional property names to extract from objects.
+     *
+     * @return  array  Returns an array according to defined options.
+     *
+     * @since   1.2.0
+     */
+    public function toArray($associative = true, ...$keys)
+    {
+        if (empty($keys)) {
+            $keys = $this->getObjectsKeys();
+        }
+
+        $return = [];
+
+        $i = 0;
+
+        foreach ($this->objects as $key => $object) {
+            $arrayItem = [];
+
+            $key = ($associative) ? $key : $i++;
+
+            $j = 0;
+
+            foreach ($keys as $property) {
+                $propertyKey             = ($associative) ? $property : $j++;
+                $arrayItem[$propertyKey] = $object->$property ?? null;
+            }
+
+            $return[$key] = $arrayItem;
+        }
+
+        return $return;
+    }
+
+    /**
+     * Gets the number of data objects in the set.
+     *
+     * @return  integer  The number of objects.
+     *
+     * @since   1.0
+     */
+    public function count()
+    {
+        return \count($this->objects);
+    }
+
+    /**
+     * Clears the objects in the data set.
+     *
+     * @return  DataSet  Returns itself to allow chaining.
+     *
+     * @since   1.0
+     */
+    public function clear()
+    {
+        $this->objects = [];
+        $this->rewind();
+
+        return $this;
+    }
+
+    /**
+     * Get the current data object in the set.
+     *
+     * @return  DataObject|false  The current object, or false if the array is empty or the pointer is beyond the end of the elements.
+     *
+     * @since   1.0
+     */
+    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 data objects in the set, dumped as a simple PHP stdClass object.
+     *
+     * @see     DataObject::dump()
+     * @since   1.0
+     */
+    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 = [];
+
+        // 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.
+     *
+     * @return  array
+     *
+     * @since   1.0
+     */
+    public function jsonSerialize()
+    {
+        $return = [];
+
+        // Iterate through the objects.
+        foreach ($this->objects as $object) {
+            // Call the method for the object.
+            $return[] = $object;
+        }
+
+        return $return;
+    }
+
+    /**
+     * Gets the key of the current object in the iterator.
+     *
+     * @return  integer|false  The object key on success; false on failure.
+     *
+     * @since   1.0
+     */
+    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   1.0
+     */
+    public function keys()
+    {
+        return array_keys($this->objects);
+    }
+
+    /**
+     * Applies a function to every object in the set (emulates array_walk).
+     *
+     * @param   callable  $funcname  Callback function.
+     *
+     * @return  boolean
+     *
+     * @since   1.2.0
+     * @throws  \InvalidArgumentException
+     */
+    public function walk(callable $funcname)
+    {
+        foreach ($this->objects as $key => $object) {
+            $funcname($object, $key);
+        }
+
+        return true;
+    }
+
+    /**
+     * Advances the iterator to the next object in the iterator.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     */
+    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
+     *
+     * @since   1.0
+     */
+    public function offsetExists($offset)
+    {
+        return isset($this->objects[$offset]);
+    }
+
+    /**
+     * Gets an offset in the iterator.
+     *
+     * @param   mixed  $offset  The object offset.
+     *
+     * @return  DataObject|null
+     *
+     * @since   1.0
+     */
+    public function offsetGet($offset)
+    {
+        return $this->objects[$offset] ?? null;
+    }
+
+    /**
+     * Sets an offset in the iterator.
+     *
+     * @param   mixed       $offset  The object offset.
+     * @param   DataObject  $object  The object object.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     * @throws  \InvalidArgumentException if an object is not an instance of DataObject.
+     */
+    public function offsetSet($offset, $object)
+    {
+        if (!($object instanceof DataObject)) {
+            throw new \InvalidArgumentException(
+                sprintf(
+                    'The $object argument must be an instance of "%s", a %s was given.',
+                    DataObject::class,
+                    \gettype($object) === 'object' ? \get_class($object) : \gettype($object)
+                )
+            );
+        }
+
+        // Set the offset.
+        if ($offset === null) {
+            $this->objects[] = $object;
+        } else {
+            $this->objects[$offset] = $object;
+        }
+    }
+
+    /**
+     * Unsets an offset in the iterator.
+     *
+     * @param   mixed  $offset  The object offset.
+     *
+     * @return  void
+     *
+     * @since   1.0
+     */
+    public function offsetUnset($offset)
+    {
+        if (!isset($this[$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   1.0
+     */
+    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
+     *
+     * @since   1.0
+     */
+    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   1.0
+     * @throws  \InvalidArgumentException if an object is not a DataObject.
+     */
+    private function initialise(array $input = [])
+    {
+        foreach ($input as $key => $object) {
+            if ($object !== null) {
+                $this[$key] = $object;
+            }
+        }
+
+        $this->rewind();
+    }
+}

libraries/vendor/joomla/data/src/DumpableInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Data Package
+ *
+ * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Data;
+
+/**
+ * An interface to define if an object is dumpable.
+ *
+ * @since  1.0
+ */
+interface DumpableInterface
+{
+    /**
+     * Dumps the data properties into an object, recursively if appropriate.
+     *
+     * @param   integer             $depth   The maximum depth of recursion.
+     *                                       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  \stdClass|array
+     *
+     * @since   1.0
+     */
+    public function dump($depth = 3, \SplObjectStorage $dumped = null);
+}