[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Data Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Data;
  10  
  11  use Joomla\Registry\Registry;
  12  
  13  /**
  14   * 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.
  15   *
  16   * @since  1.0
  17   */
  18  class DataObject implements DumpableInterface, \IteratorAggregate, \JsonSerializable, \Countable
  19  {
  20      /**
  21       * The data object properties.
  22       *
  23       * @var    array
  24       * @since  1.0
  25       */
  26      private $properties = [];
  27  
  28      /**
  29       * The class constructor.
  30       *
  31       * @param   mixed  $properties  Either an associative array or another object by which to set the initial properties of the new object.
  32       *
  33       * @since   1.0
  34       * @throws  \InvalidArgumentException
  35       */
  36  	public function __construct($properties = [])
  37      {
  38          // Check the properties input.
  39          if (!empty($properties))
  40          {
  41              // Bind the properties.
  42              $this->bind($properties);
  43          }
  44      }
  45  
  46      /**
  47       * The magic get method is used to get a data property.
  48       *
  49       * This method is a public proxy for the protected getProperty method.
  50       *
  51       * Note: Magic __get does not allow recursive calls. This can be tricky because the error generated by recursing into
  52       * __get is "Undefined property:  {CLASS}::{PROPERTY}" which is misleading. This is relevant for this class because
  53       * requesting a non-visible property can trigger a call to a sub-function. If that references the property directly in
  54       * the object, it will cause a recursion into __get.
  55       *
  56       * @param   string  $property  The name of the data property.
  57       *
  58       * @return  mixed  The value of the data property, or null if the data property does not exist.
  59       *
  60       * @see     DataObject::getProperty()
  61       * @since   1.0
  62       */
  63  	public function __get($property)
  64      {
  65          return $this->getProperty($property);
  66      }
  67  
  68      /**
  69       * The magic isset method is used to check the state of an object property.
  70       *
  71       * @param   string  $property  The name of the data property.
  72       *
  73       * @return  boolean
  74       *
  75       * @since   1.0
  76       */
  77  	public function __isset($property)
  78      {
  79          return isset($this->properties[$property]);
  80      }
  81  
  82      /**
  83       * The magic set method is used to set a data property.
  84       *
  85       * This is a public proxy for the protected setProperty method.
  86       *
  87       * @param   string  $property  The name of the data property.
  88       * @param   mixed   $value     The value to give the data property.
  89       *
  90       * @return  void
  91       *
  92       * @see     DataObject::setProperty()
  93       * @since   1.0
  94       */
  95  	public function __set($property, $value)
  96      {
  97          $this->setProperty($property, $value);
  98      }
  99  
 100      /**
 101       * The magic unset method is used to unset a data property.
 102       *
 103       * @param   string  $property  The name of the data property.
 104       *
 105       * @return  void
 106       *
 107       * @since   1.0
 108       */
 109  	public function __unset($property)
 110      {
 111          unset($this->properties[$property]);
 112      }
 113  
 114      /**
 115       * Binds an array or object to this object.
 116       *
 117       * @param   mixed    $properties   An associative array of properties or an object.
 118       * @param   boolean  $updateNulls  True to bind null values, false to ignore null values.
 119       *
 120       * @return  $this
 121       *
 122       * @since   1.0
 123       * @throws  \InvalidArgumentException
 124       */
 125  	public function bind($properties, $updateNulls = true)
 126      {
 127          // Check the properties data type.
 128          if (!\is_array($properties) && !\is_object($properties))
 129          {
 130              throw new \InvalidArgumentException(
 131                  sprintf('The $properties argument must be an array or object, a %s was given.', \gettype($properties))
 132              );
 133          }
 134  
 135          // Check if the object is traversable.
 136          if ($properties instanceof \Traversable)
 137          {
 138              // Convert iterator to array.
 139              $properties = iterator_to_array($properties);
 140          }
 141          elseif (\is_object($properties))
 142          {
 143              // Convert properties to an array.
 144              $properties = (array) $properties;
 145          }
 146  
 147          // Bind the properties.
 148          foreach ($properties as $property => $value)
 149          {
 150              // Check if the value is null and should be bound.
 151              if ($value === null && !$updateNulls)
 152              {
 153                  continue;
 154              }
 155  
 156              // Set the property.
 157              $this->setProperty($property, $value);
 158          }
 159  
 160          return $this;
 161      }
 162  
 163      /**
 164       * Dumps the data properties into an object, recursively if appropriate.
 165       *
 166       * @param   integer            $depth   The maximum depth of recursion (default = 3).
 167       *                                      For example, a depth of 0 will return a stdClass with all the properties in native
 168       *                                      form. A depth of 1 will recurse into the first level of properties only.
 169       * @param   \SplObjectStorage  $dumped  An array of already serialized objects that is used to avoid infinite loops.
 170       *
 171       * @return  \stdClass
 172       *
 173       * @since   1.0
 174       */
 175  	public function dump($depth = 3, \SplObjectStorage $dumped = null)
 176      {
 177          // Check if we should initialise the recursion tracker.
 178          if ($dumped === null)
 179          {
 180              $dumped = new \SplObjectStorage;
 181          }
 182  
 183          // Add this object to the dumped stack.
 184          $dumped->attach($this);
 185  
 186          // Setup a container.
 187          $dump = new \stdClass;
 188  
 189          // Dump all object properties.
 190          foreach (array_keys($this->properties) as $property)
 191          {
 192              // Get the property.
 193              $dump->$property = $this->dumpProperty($property, $depth, $dumped);
 194          }
 195  
 196          return $dump;
 197      }
 198  
 199      /**
 200       * Gets this object represented as an ArrayIterator.
 201       *
 202       * This allows the data properties to be access via a foreach statement.
 203       *
 204       * @return  \ArrayIterator
 205       *
 206       * @see     IteratorAggregate::getIterator()
 207       * @since   1.0
 208       */
 209  	public function getIterator()
 210      {
 211          return new \ArrayIterator($this->dump(0));
 212      }
 213  
 214      /**
 215       * Gets the data properties in a form that can be serialised to JSON format.
 216       *
 217       * @return  string
 218       *
 219       * @since   1.0
 220       */
 221  	public function jsonSerialize()
 222      {
 223          return $this->dump();
 224      }
 225  
 226      /**
 227       * Dumps a data property.
 228       *
 229       * If recursion is set, this method will dump any object implementing DumpableInterface (like DataObject and DataSet); it will
 230       * convert a DateTimeInterface object to a string; and it will convert a Joomla\Registry\Registry to an object.
 231       *
 232       * @param   string             $property  The name of the data property.
 233       * @param   integer            $depth     The current depth of recursion (a value of 0 will ignore recursion).
 234       * @param   \SplObjectStorage  $dumped    An array of already serialized objects that is used to avoid infinite loops.
 235       *
 236       * @return  mixed  The value of the dumped property.
 237       *
 238       * @since   1.0
 239       */
 240  	protected function dumpProperty($property, $depth, \SplObjectStorage $dumped)
 241      {
 242          $value = $this->getProperty($property);
 243  
 244          if ($depth > 0)
 245          {
 246              // Check if the object is also a dumpable object.
 247              if ($value instanceof DumpableInterface)
 248              {
 249                  // Do not dump the property if it has already been dumped.
 250                  if (!$dumped->contains($value))
 251                  {
 252                      $value = $value->dump($depth - 1, $dumped);
 253                  }
 254              }
 255  
 256              // Check if the object is a date.
 257              if ($value instanceof \DateTimeInterface)
 258              {
 259                  $value = $value->format('Y-m-d H:i:s');
 260              }
 261              elseif ($value instanceof Registry)
 262              {
 263                  $value = $value->toObject();
 264              }
 265          }
 266  
 267          return $value;
 268      }
 269  
 270      /**
 271       * Gets a data property.
 272       *
 273       * @param   string  $property  The name of the data property.
 274       *
 275       * @return  mixed  The value of the data property.
 276       *
 277       * @see     DataObject::__get()
 278       * @since   1.0
 279       */
 280  	protected function getProperty($property)
 281      {
 282          return $this->properties[$property] ?? null;
 283      }
 284  
 285      /**
 286       * Sets a data property.
 287       *
 288       * If the name of the property starts with a null byte, this method will return null.
 289       *
 290       * @param   string  $property  The name of the data property.
 291       * @param   mixed   $value     The value to give the data property.
 292       *
 293       * @return  mixed  The value of the data property.
 294       *
 295       * @see     DataObject::__set()
 296       * @since   1.0
 297       */
 298  	protected function setProperty($property, $value)
 299      {
 300          /*
 301           * Check if the property starts with a null byte. If so, discard it because a later attempt to try to access it
 302           * can cause a fatal error. See http://www.php.net/manual/en/language.types.array.php#language.types.array.casting
 303           */
 304          if (strpos($property, "\0") === 0)
 305          {
 306              return;
 307          }
 308  
 309          // Set the value.
 310          $this->properties[$property] = $value;
 311  
 312          return $value;
 313      }
 314  
 315      /**
 316       * Count the number of data properties.
 317       *
 318       * @return  integer  The number of data properties.
 319       *
 320       * @since   1.0
 321       */
 322  	public function count()
 323      {
 324          return \count($this->properties);
 325      }
 326  }