includes/libs/GenericArrayObject.php

   1 <?php
   2
   3 /**
   4  * Extends ArrayObject and does two things:
   5  *
   6  * Allows for deriving classes to easily intercept additions
   7  * and deletions for purposes such as additional indexing.
   8  *
   9  * Enforces the objects to be of a certain type, so this
  10  * can be replied upon, much like if this had true support
  11  * for generics, which sadly enough is not possible in PHP.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License along
  24  * with this program; if not, write to the Free Software Foundation, Inc.,
  25  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  26  * http://www.gnu.org/copyleft/gpl.html
  27  *
  28  * @since 1.20
  29  *
  30  * @file
  31  * @ingroup Diff
  32  *
  33  * @licence GNU GPL v2+
  34  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  35  */
  36 abstract class GenericArrayObject extends ArrayObject {
  37
  38         /**
  39          * Returns the name of an interface/class that the element should implement/extend.
  40          *
  41          * @since 1.20
  42          *
  43          * @return string
  44          */
  45         public abstract function getObjectType();
  46
  47         /**
  48          * @see SiteList::getNewOffset()
  49          * @since 1.20
  50          * @var integer
  51          */
  52         protected $indexOffset = 0;
  53
  54         /**
  55          * Finds a new offset for when appending an element.
  56          * The base class does this, so it would be better to integrate,
  57          * but there does not appear to be any way to do this...
  58          *
  59          * @since 1.20
  60          *
  61          * @return integer
  62          */
  63         protected function getNewOffset() {
  64                 while ( true ) {
  65                         if ( !$this->offsetExists( $this->indexOffset ) ) {
  66                                 return $this->indexOffset;
  67                         }
  68
  69                         $this->indexOffset++;
  70                 }
  71         }
  72
  73         /**
  74          * Constructor.
  75          * @see ArrayObject::__construct
  76          *
  77          * @since 1.20
  78          *
  79          * @param null|array $input
  80          * @param int $flags
  81          * @param string $iterator_class
  82          */
  83         public function __construct( $input = null, $flags = 0, $iterator_class = 'ArrayIterator' ) {
  84                 parent::__construct( array(), $flags, $iterator_class );
  85
  86                 if ( !is_null( $input ) ) {
  87                         foreach ( $input as $offset => $value ) {
  88                                 $this->offsetSet( $offset, $value );
  89                         }
  90                 }
  91         }
  92
  93         /**
  94          * @see ArrayObject::append
  95          *
  96          * @since 1.20
  97          *
  98          * @param mixed $value
  99          */
 100         public function append( $value ) {
 101                 $this->setElement( null, $value );
 102         }
 103
 104         /**
 105          * @see ArrayObject::offsetSet()
 106          *
 107          * @since 1.20
 108          *
 109          * @param mixed $index
 110          * @param mixed $value
 111          */
 112         public function offsetSet( $index, $value ) {
 113                 $this->setElement( $index, $value );
 114         }
 115
 116         /**
 117          * Returns if the provided value has the same type as the elements
 118          * that can be added to this ArrayObject.
 119          *
 120          * @since 1.20
 121          *
 122          * @param mixed $value
 123          *
 124          * @return boolean
 125          */
 126         protected function hasValidType( $value ) {
 127                 $class = $this->getObjectType();
 128                 return $value instanceof $class;
 129         }
 130
 131         /**
 132          * Method that actually sets the element and holds
 133          * all common code needed for set operations, including
 134          * type checking and offset resolving.
 135          *
 136          * If you want to do additional indexing or have code that
 137          * otherwise needs to be executed whenever an element is added,
 138          * you can overload @see preSetElement.
 139          *
 140          * @since 1.20
 141          *
 142          * @param mixed $index
 143          * @param mixed $value
 144          *
 145          * @throws Exception
 146          */
 147         protected function setElement( $index, $value ) {
 148                 if ( !$this->hasValidType( $value ) ) {
 149                         throw new Exception(
 150                                 'Can only add ' . $this->getObjectType() . ' implementing objects to ' . get_called_class() . '.'
 151                         );
 152                 }
 153
 154                 if ( is_null( $index ) ) {
 155                         $index = $this->getNewOffset();
 156                 }
 157
 158                 if ( $this->preSetElement( $index, $value ) ) {
 159                         parent::offsetSet( $index, $value );
 160                 }
 161         }
 162
 163         /**
 164          * Gets called before a new element is added to the ArrayObject.
 165          *
 166          * At this point the index is always set (ie not null) and the
 167          * value is always of the type returned by @see getObjectType.
 168          *
 169          * Should return a boolean. When false is returned the element
 170          * does not get added to the ArrayObject.
 171          *
 172          * @since 1.20
 173          *
 174          * @param integer|string $index
 175          * @param mixed $value
 176          *
 177          * @return boolean
 178          */
 179         protected function preSetElement( $index, $value ) {
 180                 return true;
 181         }
 182
 183         /**
 184          * @see Serializable::serialize
 185          *
 186          * @since 1.20
 187          *
 188          * @return string
 189          */
 190         public function serialize() {
 191                 return serialize( $this->getSerializationData() );
 192         }
 193
 194         /**
 195          * Returns an array holding all the data that should go into serialization calls.
 196          * This is intended to allow overloading without having to reimplement the
 197          * behaviour of this base class.
 198          *
 199          * @since 1.20
 200          *
 201          * @return array
 202          */
 203         protected function getSerializationData() {
 204                 return array(
 205                         'data' => $this->getArrayCopy(),
 206                         'index' => $this->indexOffset,
 207                 );
 208         }
 209
 210         /**
 211          * @see Serializable::unserialize
 212          *
 213          * @since 1.20
 214          *
 215          * @param string $serialization
 216          *
 217          * @return array
 218          */
 219         public function unserialize( $serialization ) {
 220                 $serializationData = unserialize( $serialization );
 221
 222                 foreach ( $serializationData['data'] as $offset => $value ) {
 223                         // Just set the element, bypassing checks and offset resolving,
 224                         // as these elements have already gone through this.
 225                         parent::offsetSet( $offset, $value );
 226                 }
 227
 228                 $this->indexOffset = $serializationData['index'];
 229
 230                 return $serializationData;
 231         }
 232
 233         /**
 234          * Returns if the ArrayObject has no elements.
 235          *
 236          * @since 1.20
 237          *
 238          * @return boolean
 239          */
 240         public function isEmpty() {
 241                 return $this->count() === 0;
 242         }
 243
 244 }