primo commit

libraries/vendor/joomla/registry/src/Factory.php

@@ -0,0 +1,57 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2015 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry;
+
+/**
+ * Factory class to fetch Registry objects
+ *
+ * @since  1.5.0
+ */
+class Factory
+{
+    /**
+     * Returns a FormatInterface object, only creating it if it doesn't already exist.
+     *
+     * @param  string  $type     The format to load
+     * @param  array   $options  Additional options to configure the object
+     *
+     * @return  FormatInterface  Registry format handler
+     *
+     * @throws  \InvalidArgumentException
+     *
+     * @since   1.5.0
+     * @since   2.0.0  Object caching is no longer supported. `Factory::getFormat()` returns a new `FormatInterface`
+     *          instance on each call.
+     */
+    public static function getFormat($type, array $options = [])
+    {
+        // Sanitize format type.
+        $type = \strtolower(\preg_replace('/[^A-Z\d_]/i', '', $type));
+
+        $localNamespace = __NAMESPACE__ . '\\Format';
+        $namespace      = $options['format_namespace'] ?? $localNamespace;
+        $class          = $namespace . '\\' . \ucfirst($type);
+
+        if (!\class_exists($class)) {
+            // Were we given a custom namespace?  If not, there's nothing else we can do
+            if ($namespace === $localNamespace) {
+                throw new \InvalidArgumentException(\sprintf('Unable to load format class for type "%s".', $type), 500);
+            }
+
+            $class = $localNamespace . '\\' . \ucfirst($type);
+
+            if (!\class_exists($class)) {
+                throw new \InvalidArgumentException(\sprintf('Unable to load format class for type "%s".', $type), 500);
+            }
+        }
+
+        return new $class();
+    }
+}

libraries/vendor/joomla/registry/src/Format/Ini.php

@@ -0,0 +1,309 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry\Format;
+
+use Joomla\Registry\FormatInterface;
+use Joomla\Utilities\ArrayHelper;
+
+/**
+ * INI format handler for Registry.
+ *
+ * @since  1.0.0
+ */
+class Ini implements FormatInterface
+{
+    /**
+     * Default options array
+     *
+     * @var    array
+     * @since  1.3.0
+     */
+    protected static $options = [
+        'supportArrayValues' => false,
+        'parseBooleanWords'  => false,
+        'processSections'    => false,
+    ];
+
+    /**
+     * A cache used by stringToObject.
+     *
+     * @var    array
+     * @since  1.0.0
+     */
+    protected static $cache = [];
+
+    /**
+     * Converts an object into an INI formatted string
+     * - Unfortunately, there is no way to have ini values nested further than two
+     * levels deep.  Therefore we will only go through the first two levels of
+     * the object.
+     *
+     * @param  object  $object   Data source object.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  string  INI formatted string.
+     *
+     * @since   1.0.0
+     */
+    public function objectToString($object, array $options = [])
+    {
+        $options            = \array_merge(static::$options, $options);
+        $supportArrayValues = $options['supportArrayValues'];
+
+        $local  = [];
+        $global = [];
+
+        $variables = \get_object_vars($object);
+
+        $last = \count($variables);
+
+        // Assume that the first element is in section
+        $inSection = true;
+
+        // Iterate over the object to set the properties.
+        foreach ($variables as $key => $value) {
+            // If the value is an object then we need to put it in a local section.
+            if (\is_object($value)) {
+                // Add an empty line if previous string wasn't in a section
+                if (!$inSection) {
+                    $local[] = '';
+                }
+
+                // Add the section line.
+                $local[] = '[' . $key . ']';
+
+                // Add the properties for this section.
+                foreach (\get_object_vars($value) as $k => $v) {
+                    if (\is_array($v) && $supportArrayValues) {
+                        $assoc = ArrayHelper::isAssociative($v);
+
+                        foreach ($v as $arrayKey => $item) {
+                            $arrayKey = $assoc ? $arrayKey : '';
+                            $local[]  = $k . '[' . $arrayKey . ']=' . $this->getValueAsIni($item);
+                        }
+                    } else {
+                        $local[] = $k . '=' . $this->getValueAsIni($v);
+                    }
+                }
+
+                // Add empty line after section if it is not the last one
+                if (--$last !== 0) {
+                    $local[] = '';
+                }
+            } elseif (\is_array($value) && $supportArrayValues) {
+                $assoc = ArrayHelper::isAssociative($value);
+
+                foreach ($value as $arrayKey => $item) {
+                    $arrayKey = $assoc ? $arrayKey : '';
+                    $global[] = $key . '[' . $arrayKey . ']=' . $this->getValueAsIni($item);
+                }
+            } else {
+                // Not in a section so add the property to the global array.
+                $global[]  = $key . '=' . $this->getValueAsIni($value);
+                $inSection = false;
+            }
+        }
+
+        return \implode("\n", \array_merge($global, $local));
+    }
+
+    /**
+     * Parse an INI formatted string and convert it into an object.
+     *
+     * @param  string  $data     INI formatted string to convert.
+     * @param  array   $options  An array of options used by the formatter, or a boolean setting to process sections.
+     *
+     * @return  object   Data object.
+     *
+     * @since   1.0.0
+     */
+    public function stringToObject($data, array $options = [])
+    {
+        $options = \array_merge(static::$options, $options);
+
+        // Check the memory cache for already processed strings.
+        $hash = \md5($data . ':' . (int) $options['processSections']);
+
+        if (isset(static::$cache[$hash])) {
+            return static::$cache[$hash];
+        }
+
+        // If no lines present just return the object.
+        if (empty($data)) {
+            return new \stdClass();
+        }
+
+        $obj     = new \stdClass();
+        $section = false;
+        $array   = false;
+        $lines   = \explode("\n", $data);
+
+        // Process the lines.
+        foreach ($lines as $line) {
+            // Trim any unnecessary whitespace.
+            $line = \trim($line);
+
+            // Ignore empty lines and comments.
+            if (empty($line) || ($line[0] === ';')) {
+                continue;
+            }
+
+            if ($options['processSections']) {
+                $length = \strlen($line);
+
+                // If we are processing sections and the line is a section add the object and continue.
+                if ($line[0] === '[' && ($line[$length - 1] === ']')) {
+                    $section       = \substr($line, 1, $length - 2);
+                    $obj->$section = new \stdClass();
+
+                    continue;
+                }
+            } elseif ($line[0] === '[') {
+                continue;
+            }
+
+            // Check that an equal sign exists and is not the first character of the line.
+            if (!\strpos($line, '=')) {
+                // Maybe throw exception?
+                continue;
+            }
+
+            // Get the key and value for the line.
+            [$key, $value] = \explode('=', $line, 2);
+
+            // If we have an array item
+            if (\substr($key, -1) === ']' && ($openBrace = \strpos($key, '[', 1)) !== false) {
+                if ($options['supportArrayValues']) {
+                    $array    = true;
+                    $arrayKey = \substr($key, $openBrace + 1, -1);
+
+                    // If we have a multi-dimensional array or malformed key
+                    if (\strpos($arrayKey, '[') !== false || \strpos($arrayKey, ']') !== false) {
+                        // Maybe throw exception?
+                        continue;
+                    }
+
+                    $key = \substr($key, 0, $openBrace);
+                } else {
+                    continue;
+                }
+            }
+
+            // Validate the key.
+            if (\preg_match('/[^A-Z\d_]/i', $key)) {
+                // Maybe throw exception?
+                continue;
+            }
+
+            // If the value is quoted then we assume it is a string.
+            $length = \strlen($value);
+
+            if ($length && ($value[0] === '"') && ($value[$length - 1] === '"')) {
+                // Strip the quotes and Convert the new line characters.
+                $value = \stripcslashes(\substr($value, 1, $length - 2));
+                $value = \str_replace('\n', "\n", $value);
+            } else {
+                // If the value is not quoted, we assume it is not a string.
+
+                // If the value is 'false' assume boolean false.
+                if ($value === 'false') {
+                    $value = false;
+                } elseif ($value === 'true') {
+                    // If the value is 'true' assume boolean true.
+                    $value = true;
+                } elseif ($options['parseBooleanWords'] && \in_array(\strtolower($value), ['yes', 'no'], true)) {
+                    // If the value is 'yes' or 'no' and option is enabled assume appropriate boolean
+                    $value = (\strtolower($value) === 'yes');
+                } elseif (\is_numeric($value)) {
+                    // If the value is numeric than it is either a float or int.
+                    // If there is a period then we assume a float.
+                    if (\strpos($value, '.') !== false) {
+                        $value = (float) $value;
+                    } else {
+                        $value = (int) $value;
+                    }
+                }
+            }
+
+            // If a section is set add the key/value to the section, otherwise top level.
+            if ($section) {
+                if ($array) {
+                    if (!isset($obj->$section->$key)) {
+                        $obj->$section->$key = [];
+                    }
+
+                    if (!empty($arrayKey)) {
+                        $obj->$section->{$key}[$arrayKey] = $value;
+                    } else {
+                        $obj->$section->{$key}[] = $value;
+                    }
+                } else {
+                    $obj->$section->$key = $value;
+                }
+            } else {
+                if ($array) {
+                    if (!isset($obj->$key)) {
+                        $obj->$key = [];
+                    }
+
+                    if (!empty($arrayKey)) {
+                        $obj->{$key}[$arrayKey] = $value;
+                    } else {
+                        $obj->{$key}[] = $value;
+                    }
+                } else {
+                    $obj->$key = $value;
+                }
+            }
+
+            $array = false;
+        }
+
+        // Cache the string to save cpu cycles -- thus the world :)
+        static::$cache[$hash] = clone $obj;
+
+        return $obj;
+    }
+
+    /**
+     * Method to get a value in an INI format.
+     *
+     * @param  mixed  $value  The value to convert to INI format.
+     *
+     * @return  string  The value in INI format.
+     *
+     * @since   1.0.0
+     */
+    protected function getValueAsIni($value)
+    {
+        $string = '';
+
+        switch (\gettype($value)) {
+            case 'integer':
+            case 'double':
+                $string = $value;
+
+                break;
+
+            case 'boolean':
+                $string = $value ? 'true' : 'false';
+
+                break;
+
+            case 'string':
+                // Sanitize any CRLF characters..
+                $string = '"' . \str_replace(["\r\n", "\n"], '\\n', $value) . '"';
+
+                break;
+        }
+
+        return $string;
+    }
+}

libraries/vendor/joomla/registry/src/Format/Json.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry\Format;
+
+use Joomla\Registry\Factory;
+use Joomla\Registry\FormatInterface;
+
+/**
+ * JSON format handler for Registry.
+ *
+ * @since  1.0.0
+ */
+class Json implements FormatInterface
+{
+    /**
+     * Converts an object into a JSON formatted string.
+     *
+     * @param  object  $object   Data source object.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  string  JSON formatted string.
+     *
+     * @since   1.0.0
+     */
+    public function objectToString($object, array $options = [])
+    {
+        $bitMask = $options['bitmask'] ?? 0;
+        $depth   = $options['depth'] ?? 512;
+
+        return \json_encode($object, $bitMask, $depth);
+    }
+
+    /**
+     * Parse a JSON formatted string and convert it into an object.
+     *
+     * If the string is not in JSON format, this method will attempt to parse it as INI format.
+     *
+     * @param  string  $data     JSON formatted string to convert.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  object   Data object.
+     *
+     * @throws  \RuntimeException
+     * @since   1.0.0
+     */
+    public function stringToObject($data, array $options = ['processSections' => false])
+    {
+        $data = \trim($data);
+
+        if (empty($data)) {
+            return new \stdClass();
+        }
+
+        $decoded = \json_decode($data);
+
+        // Check for an error decoding the data
+        if ($decoded === null && \json_last_error() !== JSON_ERROR_NONE) {
+            // If it's an ini file, parse as ini.
+            if ($data !== '' && $data[0] !== '{') {
+                return Factory::getFormat('Ini')->stringToObject($data, $options);
+            }
+
+            throw new \RuntimeException(\sprintf('Error decoding JSON data: %s', \json_last_error_msg()));
+        }
+
+        return (object) $decoded;
+    }
+}

libraries/vendor/joomla/registry/src/Format/Php.php

@@ -0,0 +1,139 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry\Format;
+
+use Joomla\Registry\FormatInterface;
+
+/**
+ * PHP class format handler for Registry
+ *
+ * @since  1.0.0
+ */
+class Php implements FormatInterface
+{
+    /**
+     * Converts an object into a php class string.
+     * - NOTE: Only one depth level is supported.
+     *
+     * @param  object  $object  Data Source Object
+     * @param  array   $params  Parameters used by the formatter
+     *
+     * @return  string  Config class formatted string
+     *
+     * @since   1.0.0
+     * @since   2.0.0  The PHP format respects the data type of each value when generating the PHP source code.
+     *                 Before 2.0.0, all data were converted to string notation.
+     */
+    public function objectToString($object, array $params = [])
+    {
+        // A class must be provided
+        $class = $params['class'] ?? 'Registry';
+
+        // Build the object variables string
+        $vars = '';
+
+        foreach (\get_object_vars($object) as $k => $v) {
+            $vars .= "\tpublic \$$k = " . $this->formatValue($v) . ";\n";
+        }
+
+        $str = "<?php\n";
+
+        // If supplied, add a namespace to the class object
+        if (isset($params['namespace']) && $params['namespace'] !== '') {
+            $str .= 'namespace ' . $params['namespace'] . ";\n\n";
+        }
+
+        $str .= "class $class {\n";
+        $str .= $vars;
+        $str .= '}';
+
+        // Use the closing tag if it not set to false in parameters.
+        if (!isset($params['closingtag']) || $params['closingtag'] !== false) {
+            $str .= "\n?>";
+        }
+
+        return $str;
+    }
+
+    /**
+     * Parse a PHP class formatted string and convert it into an object.
+     *
+     * @param  string  $data     PHP Class formatted string to convert.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  object   Data object.
+     *
+     * @since   1.0.0
+     */
+    public function stringToObject($data, array $options = [])
+    {
+        return new \stdClass();
+    }
+
+    /**
+     * Format a value for the string conversion
+     *
+     * @param  mixed  $value  The value to format
+     *
+     * @return  mixed  The formatted value
+     *
+     * @since   2.0.0
+     */
+    protected function formatValue($value)
+    {
+        switch (\gettype($value)) {
+            case 'string':
+                return "'" . \addcslashes($value, '\\\'') . "'";
+
+            case 'array':
+            case 'object':
+                return $this->getArrayString((array) $value);
+
+            case 'double':
+            case 'integer':
+                return $value;
+
+            case 'boolean':
+                return $value ? 'true' : 'false';
+
+            case 'NULL':
+                return 'null';
+        }
+
+        return null;
+    }
+
+    /**
+     * Method to get an array as an exported string.
+     *
+     * @param  array  $a  The array to get as a string.
+     *
+     * @return  string
+     *
+     * @since   1.0.0
+     */
+    protected function getArrayString($a)
+    {
+        $s = 'array(';
+        $i = 0;
+
+        foreach ($a as $k => $v) {
+            $s .= $i ? ', ' : '';
+            $s .= "'" . \addcslashes($k, '\\\'') . "' => ";
+            $s .= $this->formatValue($v);
+
+            $i++;
+        }
+
+        $s .= ')';
+
+        return $s;
+    }
+}

libraries/vendor/joomla/registry/src/Format/Xml.php

@@ -0,0 +1,151 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry\Format;
+
+use Joomla\Registry\FormatInterface;
+
+/**
+ * XML format handler for Registry.
+ *
+ * @since  1.0.0
+ */
+class Xml implements FormatInterface
+{
+    /**
+     * Converts an object into an XML formatted string.
+     * -    If more than two levels of nested groups are necessary, since INI is not
+     * useful, XML or another format should be used.
+     *
+     * @param  object  $object   Data source object.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  string  XML formatted string.
+     *
+     * @since   1.0.0
+     */
+    public function objectToString($object, array $options = [])
+    {
+        $rootName = $options['name'] ?? 'registry';
+        $nodeName = $options['nodeName'] ?? 'node';
+
+        // Create the root node.
+        $root = \simplexml_load_string('<' . $rootName . ' />');
+
+        // Iterate over the object members.
+        $this->getXmlChildren($root, $object, $nodeName);
+
+        return $root->asXML();
+    }
+
+    /**
+     * Parse a XML formatted string and convert it into an object.
+     *
+     * @param  string  $data     XML formatted string to convert.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  object   Data object.
+     *
+     * @since   1.0.0
+     */
+    public function stringToObject($data, array $options = [])
+    {
+        $obj = new \stdClass();
+
+        // Parse the XML string.
+        $xml = \simplexml_load_string($data);
+
+        foreach ($xml->children() as $node) {
+            $obj->{$node['name']} = $this->getValueFromNode($node);
+        }
+
+        return $obj;
+    }
+
+    /**
+     * Method to get a PHP native value for a SimpleXMLElement object. -- called recursively
+     *
+     * @param  \SimpleXMLElement  $node  SimpleXMLElement object for which to get the native value.
+     *
+     * @return  mixed  Native value of the SimpleXMLElement object.
+     *
+     * @since   1.0.0
+     */
+    protected function getValueFromNode($node)
+    {
+        switch ($node['type']) {
+            case 'integer':
+                $value = (string) $node;
+
+                return (int) $value;
+
+            case 'string':
+                return (string) $node;
+
+            case 'boolean':
+                $value = (string) $node;
+
+                return (bool) $value;
+
+            case 'double':
+                $value = (string) $node;
+
+                return (float) $value;
+
+            case 'array':
+                $value = [];
+
+                foreach ($node->children() as $child) {
+                    $value[(string) $child['name']] = $this->getValueFromNode($child);
+                }
+
+                break;
+
+            default:
+                $value = new \stdClass();
+
+                foreach ($node->children() as $child) {
+                    $value->{$child['name']} = $this->getValueFromNode($child);
+                }
+
+                break;
+        }
+
+        return $value;
+    }
+
+    /**
+     * Method to build a level of the XML string -- called recursively
+     *
+     * @param  \SimpleXMLElement  $node      SimpleXMLElement object to attach children.
+     * @param  object             $var       Object that represents a node of the XML document.
+     * @param  string             $nodeName  The name to use for node elements.
+     *
+     * @return  void
+     *
+     * @since   1.0.0
+     */
+    protected function getXmlChildren(\SimpleXMLElement $node, $var, $nodeName)
+    {
+        // Iterate over the object members.
+        foreach ((array) $var as $k => $v) {
+            if (\is_scalar($v)) {
+                $n = $node->addChild($nodeName, $v);
+                $n->addAttribute('name', $k);
+                $n->addAttribute('type', \gettype($v));
+            } else {
+                $n = $node->addChild($nodeName);
+                $n->addAttribute('name', $k);
+                $n->addAttribute('type', \gettype($v));
+
+                $this->getXmlChildren($n, $v, $nodeName);
+            }
+        }
+    }
+}

libraries/vendor/joomla/registry/src/Format/Yaml.php

@@ -0,0 +1,95 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry\Format;
+
+use Joomla\Registry\FormatInterface;
+use Symfony\Component\Yaml\Dumper as SymfonyYamlDumper;
+use Symfony\Component\Yaml\Parser as SymfonyYamlParser;
+use Symfony\Component\Yaml\Yaml as SymfonyYaml;
+
+/**
+ * YAML format handler for Registry.
+ *
+ * @since  1.0.0
+ */
+class Yaml implements FormatInterface
+{
+    /**
+     * The YAML parser class.
+     *
+     * @var    SymfonyYamlParser
+     * @since  1.0.0
+     */
+    private $parser;
+
+    /**
+     * The YAML dumper class.
+     *
+     * @var    SymfonyYamlDumper
+     * @since  1.0.0
+     */
+    private $dumper;
+
+    /**
+     * Construct to set up the parser and dumper
+     *
+     * @since   1.0.0
+     */
+    public function __construct()
+    {
+        if (!\class_exists(SymfonyYaml::class)) {
+            throw new \RuntimeException(
+                \sprintf(
+                    'The "%s" class could not be found, make sure you have installed the "symfony/yaml" package.',
+                    SymfonyYaml::class
+                )
+            );
+        }
+
+        $this->parser = new SymfonyYamlParser();
+        $this->dumper = new SymfonyYamlDumper();
+    }
+
+    /**
+     * Converts an object into a YAML formatted string.
+     * We use json_* to convert the passed object to an array.
+     *
+     * @param  object|array  $object   Data source object.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  string  YAML formatted string.
+     *
+     * @since   1.0.0
+     */
+    public function objectToString($object, array $options = [])
+    {
+        $array = \json_decode(\json_encode($object), true);
+
+        return $this->dumper->dump($array, 2, 0);
+    }
+
+    /**
+     * Parse a YAML formatted string and convert it into an object.
+     * We use the json_* methods to convert the parsed YAML array to an object.
+     *
+     * @param  string  $data     YAML formatted string to convert.
+     * @param  array   $options  Options used by the formatter.
+     *
+     * @return  object  Data object.
+     *
+     * @since   1.0.0
+     */
+    public function stringToObject($data, array $options = [])
+    {
+        $array = $this->parser->parse(\trim($data));
+
+        return (object) \json_decode(\json_encode($array));
+    }
+}

libraries/vendor/joomla/registry/src/FormatInterface.php

@@ -0,0 +1,46 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2015 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry;
+
+/**
+ * Interface defining a format object
+ *
+ * @since  1.5.0
+ * @since  1.5.0  Deprecated `AbstractRegistryFormat` in favor of the `FormatInterface`.
+ * @since  2.0.0  Deprecated `AbstractRegistryFormat`. Format objects must now implement the `FormatInterface`.
+ */
+interface FormatInterface
+{
+    /**
+     * Converts an object into a formatted string.
+     *
+     * @param  object  $object   Data Source Object.
+     * @param  array   $options  An array of options for the formatter.
+     *
+     * @return  string  Formatted string.
+     *
+     * @since   1.5.0
+     * @since   2.0.0  The `FormatInterface::objectToString()` method typehints the `$options` argument as an array;
+     *                 this was not enforced before 2.0.0 with `AbstractRegistryFormat::objectToString()`.
+     */
+    public function objectToString($object, array $options = []);
+
+    /**
+     * Converts a formatted string into an object.
+     *
+     * @param  string  $data     Formatted string
+     * @param  array   $options  An array of options for the formatter.
+     *
+     * @return  object  Data Object
+     *
+     * @since   1.5.0
+     */
+    public function stringToObject($data, array $options = []);
+}

libraries/vendor/joomla/registry/src/Registry.php

@@ -0,0 +1,941 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Registry Package
+ *
+ * @copyright  Copyright (C) 2013 Open Source Matters, Inc.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Registry;
+
+use Joomla\Utilities\ArrayHelper;
+
+/**
+ * Registry class
+ *
+ * @since  1.0.0
+ * @since  2.0.0  `Registry::getInstance()` was removed. Instantiate a new Registry instance instead.
+ */
+class Registry implements \JsonSerializable, \ArrayAccess, \IteratorAggregate, \Countable
+{
+    /**
+     * Registry Object
+     *
+     * @var    \stdClass
+     * @since  1.0.0
+     */
+    protected $data;
+
+    /**
+     * Flag if the Registry data object has been initialized
+     *
+     * @var    boolean
+     * @since  1.5.2
+     */
+    protected $initialized = false;
+
+    /**
+     * Path separator
+     *
+     * @var    string
+     * @since  1.4.0
+     */
+    protected $separator = '.';
+
+    /**
+     * Constructor
+     *
+     * @param  mixed   $data       The data to bind to the new Registry object.
+     * @param  string  $separator  The path separator, and empty string will flatten the registry.
+     *
+     * @since   1.0.0
+     */
+    public function __construct($data = null, string $separator = '.')
+    {
+        $this->separator = $separator;
+
+        // Instantiate the internal data object.
+        $this->data = new \stdClass();
+
+        // Optionally load supplied data.
+        if ($data instanceof self) {
+            $this->merge($data);
+        } elseif (\is_array($data) || \is_object($data)) {
+            $this->bindData($this->data, $data);
+        } elseif (!empty($data) && \is_string($data)) {
+            $this->loadString($data);
+        }
+    }
+
+    /**
+     * Magic function to clone the registry object.
+     *
+     * @return  void
+     *
+     * @since   1.0.0
+     */
+    public function __clone()
+    {
+        $this->data = \unserialize(\serialize($this->data));
+    }
+
+    /**
+     * Magic function to render this object as a string using default args of toString method.
+     *
+     * @return  string
+     *
+     * @since   1.0.0
+     */
+    public function __toString()
+    {
+        return $this->toString();
+    }
+
+    /**
+     * Count elements of the data object
+     *
+     * @return  integer  The custom count as an integer.
+     *
+     * @link    https://www.php.net/manual/en/countable.count.php
+     * @since   1.3.0
+     */
+    #[\ReturnTypeWillChange]
+    public function count()
+    {
+        return \count(\get_object_vars($this->data));
+    }
+
+    /**
+     * Implementation for the JsonSerializable interface.
+     * Allows us to pass Registry objects to json_encode.
+     *
+     * @return  object
+     *
+     * @since   1.0.0
+     * @note    The interface is only present in PHP 5.4 and up.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+
+    /**
+     * Sets a default value if not already assigned.
+     *
+     * @param  string  $key      The name of the parameter.
+     * @param  mixed   $default  An optional value for the parameter.
+     *
+     * @return  mixed  The value set, or the default if the value was not previously set (or null).
+     *
+     * @since   1.0.0
+     */
+    public function def($key, $default = '')
+    {
+        $value = $this->get($key, $default);
+        $this->set($key, $value);
+
+        return $value;
+    }
+
+    /**
+     * Check if a registry path exists.
+     *
+     * @param  string  $path  Registry path (e.g. joomla.content.showauthor)
+     *
+     * @return  boolean
+     *
+     * @since   1.0.0
+     */
+    public function exists($path)
+    {
+        // Return default value if path is empty
+        if (empty($path)) {
+            return false;
+        }
+
+        // Explode the registry path into an array
+        if ($this->separator === null || $this->separator === '') {
+            $nodes = [$path];
+        } else {
+            $nodes = \explode($this->separator, $path);
+        }
+
+        // Initialize the current node to be the registry root.
+        $node  = $this->data;
+        $found = false;
+
+        // Traverse the registry to find the correct node for the result.
+        foreach ($nodes as $n) {
+            if (\is_array($node) && isset($node[$n])) {
+                $node  = $node[$n];
+                $found = true;
+
+                continue;
+            }
+
+            if (!isset($node->$n)) {
+                return false;
+            }
+
+            $node  = $node->$n;
+            $found = true;
+        }
+
+        return $found;
+    }
+
+    /**
+     * Get a registry value.
+     *
+     * @param  string  $path     Registry path (e.g. joomla.content.showauthor)
+     * @param  mixed   $default  Optional default value, returned if the internal value is null.
+     *
+     * @return  mixed  Value of entry or null
+     *
+     * @since   1.0.0
+     */
+    public function get($path, $default = null)
+    {
+        // Return default value if path is empty
+        if (empty($path)) {
+            return $default;
+        }
+
+        if ($this->separator === null || $this->separator === '' || !\strpos($path, $this->separator)) {
+            return (isset($this->data->$path) && $this->data->$path !== null && $this->data->$path !== '')
+                ? $this->data->$path
+                : $default;
+        }
+
+        // Explode the registry path into an array
+        $nodes = \explode($this->separator, \trim($path));
+
+        // Initialize the current node to be the registry root.
+        $node  = $this->data;
+        $found = false;
+
+        // Traverse the registry to find the correct node for the result.
+        foreach ($nodes as $n) {
+            if (\is_array($node) && isset($node[$n])) {
+                $node  = $node[$n];
+                $found = true;
+
+                continue;
+            }
+
+            if (!isset($node->$n)) {
+                return $default;
+            }
+
+            $node  = $node->$n;
+            $found = true;
+        }
+
+        if (!$found || $node === null || $node === '') {
+            return $default;
+        }
+
+        return $node;
+    }
+
+    /**
+     * Gets this object represented as an ArrayIterator.
+     *
+     * This allows the data properties to be accessed via a foreach statement.
+     *
+     * @return  \ArrayIterator  This object represented as an ArrayIterator.
+     *
+     * @see     \IteratorAggregate::getIterator()
+     * @since   1.3.0
+     */
+    #[\ReturnTypeWillChange]
+    public function getIterator()
+    {
+        return new \ArrayIterator($this->data);
+    }
+
+    /**
+     * Load an associative array of values into the default namespace
+     *
+     * @param  array    $array      Associative array of value to load
+     * @param  boolean  $flattened  Load from a one-dimensional array
+     * @param  string   $separator  The key separator
+     *
+     * @return  $this
+     *
+     * @since   1.0.0
+     * @since   2.0.0  The parameter `$array` is now type hinted as `array`. Before 2.0.0, the type was not enforced.
+     */
+    public function loadArray(array $array, $flattened = false, $separator = null)
+    {
+        if (!$flattened) {
+            $this->bindData($this->data, $array);
+
+            return $this;
+        }
+
+        foreach ($array as $k => $v) {
+            $this->set($k, $v, $separator);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Load the public variables of the object into the default namespace.
+     *
+     * @param  object  $object  The object holding the publics to load
+     *
+     * @return  $this
+     *
+     * @since   1.0.0
+     */
+    public function loadObject($object)
+    {
+        $this->bindData($this->data, $object);
+
+        return $this;
+    }
+
+    /**
+     * Load the contents of a file into the registry
+     *
+     * @param  string  $file     Path to file to load
+     * @param  string  $format   Format of the file [optional: defaults to JSON]
+     * @param  array   $options  Options used by the formatter
+     *
+     * @return  $this
+     *
+     * @since   1.0.0
+     * @since   2.0.0  The parameter `$options` is now type hinted as `array`. Before 2.0.0, the type was not enforced.
+     */
+    public function loadFile($file, $format = 'JSON', array $options = [])
+    {
+        $data = \file_get_contents($file);
+
+        return $this->loadString($data, $format, $options);
+    }
+
+    /**
+     * Load a string into the registry
+     *
+     * @param  string  $data     String to load into the registry
+     * @param  string  $format   Format of the string
+     * @param  array   $options  Options used by the formatter
+     *
+     * @return  $this
+     *
+     * @since   1.0.0
+     * @since   2.0.0  The parameter `$options` is now type hinted as `array`. Before 2.0.0, the type was not enforced.
+     */
+    public function loadString($data, $format = 'JSON', array $options = [])
+    {
+        // Load a string into the given namespace [or default namespace if not given]
+        $obj = Factory::getFormat($format, $options)->stringToObject($data, $options);
+
+        // If the data object has not yet been initialized, direct assign the object
+        if (!$this->initialized) {
+            $this->data        = $obj;
+            $this->initialized = true;
+
+            return $this;
+        }
+
+        $this->loadObject($obj);
+
+        return $this;
+    }
+
+    /**
+     * Merge a Registry object into this one
+     *
+     * @param  Registry  $source     Source Registry object to merge.
+     * @param  boolean   $recursive  True to support recursive merge the children values.
+     *
+     * @return  $this
+     *
+     * @since   1.0.0
+     * @since   2.0.0  The parameter `$source` is now type hinted as `Registry`. Before 2.0.0, `Registry::merge()` just
+     *          returned `false` if `$source` was not a `Registry`.
+     */
+    public function merge(Registry $source, $recursive = false)
+    {
+        $this->bindData($this->data, $source->toArray(), $recursive, false);
+
+        return $this;
+    }
+
+    /**
+     * Method to extract a sub-registry from path
+     *
+     * @param  string  $path  Registry path (e.g. joomla.content.showauthor)
+     *
+     * @return  Registry  Registry object (empty if no data is present)
+     *
+     * @since   1.2.0
+     * @since   2.0.0  `Registry:extract()` now always returns a `Registry` object. Before 2.0.0, `null` was returned
+     *          if there was no data for the key.
+     */
+    public function extract($path)
+    {
+        $data = $this->get($path);
+
+        return new Registry($data);
+    }
+
+    /**
+     * Checks whether an offset exists in the iterator.
+     *
+     * @param  mixed  $offset  The array offset.
+     *
+     * @return  boolean  True if the offset exists, false otherwise.
+     *
+     * @since   1.0.0
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetExists($offset)
+    {
+        return $this->exists($offset);
+    }
+
+    /**
+     * Gets an offset in the iterator.
+     *
+     * @param  mixed  $offset  The array offset.
+     *
+     * @return  mixed  The array value if it exists, null otherwise.
+     *
+     * @since   1.0.0
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet($offset)
+    {
+        return $this->get($offset);
+    }
+
+    /**
+     * Sets an offset in the iterator.
+     *
+     * @param  mixed  $offset  The array offset.
+     * @param  mixed  $value   The array value.
+     *
+     * @return  void
+     *
+     * @since   1.0.0
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetSet($offset, $value)
+    {
+        $this->set($offset, $value);
+    }
+
+    /**
+     * Unsets an offset in the iterator.
+     *
+     * @param  mixed  $offset  The array offset.
+     *
+     * @return  void
+     *
+     * @since   1.0.0
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetUnset($offset)
+    {
+        $this->remove($offset);
+    }
+
+    /**
+     * Set a registry value.
+     *
+     * @param  string  $path       Registry Path (e.g. joomla.content.showauthor)
+     * @param  mixed   $value      Value of entry
+     * @param  string  $separator  The key separator. Will be removed in version 4.
+     *
+     * @return  mixed  The value of the that has been set.
+     *
+     * @since   1.0.0
+     */
+    public function set($path, $value, $separator = null)
+    {
+        if ($separator === null) {
+            $separator = $this->separator;
+        } else {
+            \trigger_deprecation(
+                'joomla/registry',
+                '__DEPLOY_VERSION__',
+                'The $separator parameter will be removed in version 4.',
+                self::class,
+                self::class
+            );
+        }
+
+        /*
+         * Explode the registry path into an array and remove empty
+         * nodes that occur as a result of a double separator. ex: joomla..test
+         * Finally, re-key the array so they are sequential.
+         */
+        if ($separator === null || $separator === '') {
+            $nodes = [$path];
+        } else {
+            $nodes = \array_values(\array_filter(\explode($separator, $path), 'strlen'));
+        }
+
+        if (!$nodes) {
+            return null;
+        }
+
+        // Initialize the current node to be the registry root.
+        $node = $this->data;
+
+        // Traverse the registry to find the correct node for the result.
+        for ($i = 0, $n = \count($nodes) - 1; $i < $n; $i++) {
+            if (\is_object($node)) {
+                if (!isset($node->{$nodes[$i]})) {
+                    $node->{$nodes[$i]} = new \stdClass();
+                }
+
+                // Pass the child as pointer in case it is an object
+                $node = &$node->{$nodes[$i]};
+
+                continue;
+            }
+
+            if (\is_array($node)) {
+                if (!isset($node[$nodes[$i]])) {
+                    $node[$nodes[$i]] = new \stdClass();
+                }
+
+                // Pass the child as pointer in case it is an array
+                $node = &$node[$nodes[$i]];
+            }
+        }
+
+        // Get the old value if exists so we can return it
+        switch (true) {
+            case (\is_object($node)):
+                $result             = $node->{$nodes[$i]} ?? null;
+                $node->{$nodes[$i]} = $value;
+                break;
+
+            case (\is_array($node)):
+                $result           = $node[$nodes[$i]] ?? null;
+                $node[$nodes[$i]] = $value;
+                break;
+
+            default:
+                $result = null;
+                break;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Append value to a path in registry
+     *
+     * @param  string  $path   Parent registry Path (e.g. joomla.content.showauthor)
+     * @param  mixed   $value  Value of entry
+     *
+     * @return  mixed  The value of the that has been set.
+     *
+     * @since   1.4.0
+     */
+    public function append($path, $value)
+    {
+        $result = null;
+
+        /*
+         * Explode the registry path into an array and remove empty
+         * nodes that occur as a result of a double dot. ex: joomla..test
+         * Finally, re-key the array so they are sequential.
+         */
+        if ($this->separator === null || $this->separator === '') {
+            $nodes = [$path];
+        } else {
+            $nodes = \array_values(\array_filter(\explode($this->separator, $path), 'strlen'));
+        }
+
+        if ($nodes) {
+            // Initialize the current node to be the registry root.
+            $node = $this->data;
+
+            // Traverse the registry to find the correct node for the result.
+            // TODO Create a new private method from part of code below, as it is almost equal to 'set' method
+            for ($i = 0, $n = \count($nodes) - 1; $i <= $n; $i++) {
+                if (\is_object($node)) {
+                    if (!isset($node->{$nodes[$i]}) && ($i !== $n)) {
+                        $node->{$nodes[$i]} = new \stdClass();
+                    }
+
+                    // Pass the child as pointer in case it is an array
+                    $node = &$node->{$nodes[$i]};
+                } elseif (\is_array($node)) {
+                    if (($i !== $n) && !isset($node[$nodes[$i]])) {
+                        $node[$nodes[$i]] = new \stdClass();
+                    }
+
+                    // Pass the child as pointer in case it is an array
+                    $node = &$node[$nodes[$i]];
+                }
+            }
+
+            if (!\is_array($node)) {
+                // Convert the node to array to make append possible
+                $node = \get_object_vars($node);
+            }
+
+            $node[] = $value;
+            $result = $value;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Delete a registry value
+     *
+     * @param  string  $path  Registry Path (e.g. joomla.content.showauthor)
+     *
+     * @return  mixed  The value of the removed node or null if not set
+     *
+     * @since   1.6.0
+     */
+    public function remove($path)
+    {
+        // Cheap optimisation to direct remove the node if there is no separator
+        if ($this->separator === null || $this->separator === '' || !\strpos($path, $this->separator)) {
+            $result = (isset($this->data->$path) && $this->data->$path !== null && $this->data->$path !== '')
+                ? $this->data->$path
+                : null;
+
+            unset($this->data->$path);
+
+            return $result;
+        }
+
+        /*
+         * Explode the registry path into an array and remove empty
+         * nodes that occur as a result of a double separator. ex: joomla..test
+         * Finally, re-key the array so they are sequential.
+         */
+        $nodes = \array_values(\array_filter(\explode($this->separator, $path), 'strlen'));
+
+        if (!$nodes) {
+            return null;
+        }
+
+        // Initialize the current node to be the registry root.
+        $node   = $this->data;
+        $parent = null;
+
+        // Traverse the registry to find the correct node for the result.
+        for ($i = 0, $n = \count($nodes) - 1; $i < $n; $i++) {
+            if (\is_object($node)) {
+                if (!isset($node->{$nodes[$i]})) {
+                    continue;
+                }
+
+                $parent = &$node;
+                $node   = $node->{$nodes[$i]};
+
+                continue;
+            }
+
+            if (\is_array($node)) {
+                if (!isset($node[$nodes[$i]])) {
+                    continue;
+                }
+
+                $parent = &$node;
+                $node   = $node[$nodes[$i]];
+
+                continue;
+            }
+        }
+
+        // Get the old value if exists so we can return it
+        switch (true) {
+            case \is_object($node):
+                $result = $node->{$nodes[$i]} ?? null;
+                unset($parent->{$nodes[$i]});
+                break;
+
+            case \is_array($node):
+                $result = $node[$nodes[$i]] ?? null;
+                unset($parent[$nodes[$i]]);
+                break;
+
+            default:
+                $result = null;
+                break;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Transforms a namespace to an array
+     *
+     * @return  array  An associative array holding the namespace data
+     *
+     * @since   1.0.0
+     */
+    public function toArray()
+    {
+        return $this->asArray($this->data);
+    }
+
+    /**
+     * Transforms a namespace to an object
+     *
+     * @return  object   An an object holding the namespace data
+     *
+     * @since   1.0.0
+     */
+    public function toObject()
+    {
+        return $this->data;
+    }
+
+    /**
+     * Get a namespace in a given string format
+     *
+     * @param  string  $format   Format to return the string in
+     * @param  array   $options  Parameters used by the formatter, see formatters for more info
+     *
+     * @return  string   Namespace in string format
+     *
+     * @since   1.0.0
+     */
+    public function toString($format = 'JSON', array $options = [])
+    {
+        return Factory::getFormat($format, $options)->objectToString($this->data, $options);
+    }
+
+    /**
+     * Method to recursively bind data to a parent object.
+     *
+     * @param  object   $parent     The parent object on which to attach the data values.
+     * @param  mixed    $data       An array or object of data to bind to the parent object.
+     * @param  boolean  $recursive  True to support recursive bindData.
+     * @param  boolean  $allowNull  True to allow null values.
+     *
+     * @return  void
+     *
+     * @since   1.0.0
+     */
+    protected function bindData($parent, $data, $recursive = true, $allowNull = true)
+    {
+        // The data object is now initialized
+        $this->initialized = true;
+
+        // Ensure the input data is an array.
+        $data = \is_object($data) ? \get_object_vars($data) : (array) $data;
+
+        foreach ($data as $k => $v) {
+            if (!$allowNull && !(($v !== null) && ($v !== ''))) {
+                continue;
+            }
+
+            if ($recursive && ((\is_array($v) && ArrayHelper::isAssociative($v)) || \is_object($v))) {
+                if (!isset($parent->$k)) {
+                    $parent->$k = new \stdClass();
+                }
+
+                $this->bindData($parent->$k, $v);
+
+                continue;
+            }
+
+            $parent->$k = $v;
+        }
+    }
+
+    /**
+     * Method to recursively convert an object of data to an array.
+     *
+     * @param  object  $data  An object of data to return as an array.
+     *
+     * @return  array  Array representation of the input object.
+     *
+     * @since   1.0.0
+     */
+    protected function asArray($data)
+    {
+        $array = [];
+
+        if (\is_object($data)) {
+            $data = \get_object_vars($data);
+        }
+
+        foreach ($data as $k => $v) {
+            if (\is_object($v) || \is_array($v)) {
+                $array[$k] = $this->asArray($v);
+
+                continue;
+            }
+
+            $array[$k] = $v;
+        }
+
+        return $array;
+    }
+
+    /**
+     * Dump to one dimension array.
+     *
+     * @param  string  $separator  The key separator.
+     *
+     * @return  string[]  Dumped array.
+     *
+     * @since   1.3.0
+     */
+    public function flatten($separator = null)
+    {
+        $array = [];
+
+        if (empty($separator)) {
+            $separator = $this->separator;
+        }
+
+        $this->toFlatten($separator, $this->data, $array);
+
+        return $array;
+    }
+
+    /**
+     * Method to recursively convert data to one dimension array.
+     *
+     * @param  string        $separator  The key separator.
+     * @param  array|object  $data       Data source of this scope.
+     * @param  array         $array      The result array, it is passed by reference.
+     * @param  string        $prefix     Last level key prefix.
+     *
+     * @return  void
+     *
+     * @since   1.3.0
+     * @since   2.0.0  The parameter `$array` is now type hinted as `array`. Before 2.0.0, the type was not enforced.
+     */
+    protected function toFlatten($separator = null, $data = null, array &$array = [], $prefix = '')
+    {
+        $data = (array) $data;
+
+        if (empty($separator)) {
+            $separator = $this->separator;
+        }
+
+        foreach ($data as $k => $v) {
+            $key = $prefix ? $prefix . $separator . $k : $k;
+
+            if (\is_object($v) || \is_array($v)) {
+                $this->toFlatten($separator, $v, $array, $key);
+
+                continue;
+            }
+
+            $array[$key] = $v;
+        }
+    }
+
+    /**
+     * Magic method to access separator property.
+     *
+     * @param  string  $name  The name of the property.
+     *
+     * @return string|null A value if the property name is valid, null otherwise.
+     *
+     * @since       __DEPLOY_VERSION__
+     * @deprecated  3.0  This is a B/C proxy for deprecated read accesses
+     */
+    public function __get($name)
+    {
+        switch ($name) {
+            case 'separator':
+                \trigger_deprecation(
+                    'joomla/registry',
+                    '__DEPLOY_VERSION__',
+                    'The $separator parameter will be removed in version 3.',
+                    self::class,
+                    self::class
+                );
+
+                return $this->separator;
+
+            default:
+                if (property_exists($this, $name)) {
+                    throw new \RuntimeException(
+                        \sprintf(
+                            'Cannot access protected or private property %s::$%s',
+                            __CLASS__,
+                            $name
+                        )
+                    );
+                }
+
+                $trace = \debug_backtrace();
+                \trigger_error(
+                    \sprintf(
+                        'Undefined property via __get(): %1$s in %2$s on line %3$s',
+                        $name,
+                        $trace[0]['file'],
+                        $trace[0]['line']
+                    ),
+                    E_USER_NOTICE
+                );
+
+                return null;
+        }
+    }
+
+    /**
+     * Magic method to access separator property.
+     *
+     * @param  string  $name   The name of the property.
+     * @param  mixed   $value  The value of the property.
+     *
+     * @return void
+     *
+     * @since       __DEPLOY_VERSION__
+     * @deprecated  3.0  This is a B/C proxy for deprecated read accesses
+     */
+    public function __set($name, $value)
+    {
+        switch ($name) {
+            case 'separator':
+                \trigger_deprecation(
+                    'joomla/registry',
+                    '__DEPLOY_VERSION__',
+                    'The $separator parameter will be removed in version 3.',
+                    self::class,
+                    self::class
+                );
+
+                $this->separator = $value;
+                break;
+
+            default:
+                if (property_exists($this, $name)) {
+                    throw new \RuntimeException(
+                        \sprintf(
+                            'Cannot access protected or private property %s::$%s',
+                            __CLASS__,
+                            $name
+                        )
+                    );
+                }
+
+                \trigger_deprecation(
+                    'joomla/registry',
+                    '__DEPLOY_VERSION__',
+                    'Creating a property will be removed in version 3.',
+                    self::class,
+                    self::class
+                );
+
+                $this->$name = $value;
+                break;
+        }
+    }
+}