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  *
  32  * @license GNU GPL v2+
  33  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  34  */
  35 abstract class GenericArrayObject extends ArrayObject {
  36
  37         /**
  38          * Returns the name of an interface/class that the element should implement/extend.
  39          *
  40          * @since 1.20
  41          *
  42          * @return string
  43          */
  44         abstract public function getObjectType();
  45
  46         /**
  47          * @see SiteList::getNewOffset()
  48          * @since 1.20
  49          * @var integer
  50          */
  51         protected $indexOffset = 0;
  52
  53         /**
  54          * Finds a new offset for when appending an element.
  55          * The base class does this, so it would be better to integrate,
  56          * but there does not appear to be any way to do this...
  57          *
  58          * @since 1.20
  59          *
  60          * @return integer
  61          */
  62         protected function getNewOffset() {
  63                 while ( $this->offsetExists( $this->indexOffset ) ) {
  64                         $this->indexOffset++;
  65                 }
  66
  67                 return $this->indexOffset;
  68         }
  69
  70         /**
  71          * Constructor.
  72          * @see ArrayObject::__construct
  73          *
  74          * @since 1.20
  75          *
  76          * @param null|array $input
  77          * @param int $flags
  78          * @param string $iterator_class
  79          */
  80         public function __construct( $input = null, $flags = 0, $iterator_class = 'ArrayIterator' ) {
  81                 parent::__construct( array(), $flags, $iterator_class );
  82
  83                 if ( !is_null( $input ) ) {
  84                         foreach ( $input as $offset => $value ) {
  85                                 $this->offsetSet( $offset, $value );
  86                         }
  87                 }
  88         }
  89
  90         /**
  91          * @see ArrayObject::append
  92          *
  93          * @since 1.20
  94          *
  95          * @param mixed $value
  96          */
  97         public function append( $value ) {
  98                 $this->setElement( null, $value );
  99         }
 100
 101         /**
 102          * @see ArrayObject::offsetSet()
 103          *
 104          * @since 1.20
 105          *
 106          * @param mixed $index
 107          * @param mixed $value
 108          */
 109         public function offsetSet( $index, $value ) {
 110                 $this->setElement( $index, $value );
 111         }
 112
 113         /**
 114          * Returns if the provided value has the same type as the elements
 115          * that can be added to this ArrayObject.
 116          *
 117          * @since 1.20
 118          *
 119          * @param mixed $value
 120          *
 121          * @return boolean
 122          */
 123         protected function hasValidType( $value ) {
 124                 $class = $this->getObjectType();
 125                 return $value instanceof $class;
 126         }
 127
 128         /**
 129          * Method that actually sets the element and holds
 130          * all common code needed for set operations, including
 131          * type checking and offset resolving.
 132          *
 133          * If you want to do additional indexing or have code that
 134          * otherwise needs to be executed whenever an element is added,
 135          * you can overload @see preSetElement.
 136          *
 137          * @since 1.20
 138          *
 139          * @param mixed $index
 140          * @param mixed $value
 141          *
 142          * @throws InvalidArgumentException
 143          */
 144         protected function setElement( $index, $value ) {
 145                 if ( !$this->hasValidType( $value ) ) {
 146                         throw new InvalidArgumentException(
 147                                 'Can only add ' . $this->getObjectType() . ' implementing objects to ' . get_called_class() . '.'
 148                         );
 149                 }
 150
 151                 if ( is_null( $index ) ) {
 152                         $index = $this->getNewOffset();
 153                 }
 154
 155                 if ( $this->preSetElement( $index, $value ) ) {
 156                         parent::offsetSet( $index, $value );
 157                 }
 158         }
 159
 160         /**
 161          * Gets called before a new element is added to the ArrayObject.
 162          *
 163          * At this point the index is always set (ie not null) and the
 164          * value is always of the type returned by @see getObjectType.
 165          *
 166          * Should return a boolean. When false is returned the element
 167          * does not get added to the ArrayObject.
 168          *
 169          * @since 1.20
 170          *
 171          * @param integer|string $index
 172          * @param mixed $value
 173          *
 174          * @return boolean
 175          */
 176         protected function preSetElement( $index, $value ) {
 177                 return true;
 178         }
 179
 180         /**
 181          * @see Serializable::serialize
 182          *
 183          * @since 1.20
 184          *
 185          * @return string
 186          */
 187         public function serialize() {
 188                 return serialize( $this->getSerializationData() );
 189         }
 190
 191         /**
 192          * Returns an array holding all the data that should go into serialization calls.
 193          * This is intended to allow overloading without having to reimplement the
 194          * behavior of this base class.
 195          *
 196          * @since 1.20
 197          *
 198          * @return array
 199          */
 200         protected function getSerializationData() {
 201                 return array(
 202                         'data' => $this->getArrayCopy(),
 203                         'index' => $this->indexOffset,
 204                 );
 205         }
 206
 207         /**
 208          * @see Serializable::unserialize
 209          *
 210          * @since 1.20
 211          *
 212          * @param string $serialization
 213          *
 214          * @return array
 215          */
 216         public function unserialize( $serialization ) {
 217                 $serializationData = unserialize( $serialization );
 218
 219                 foreach ( $serializationData['data'] as $offset => $value ) {
 220                         // Just set the element, bypassing checks and offset resolving,
 221                         // as these elements have already gone through this.
 222                         parent::offsetSet( $offset, $value );
 223                 }
 224
 225                 $this->indexOffset = $serializationData['index'];
 226
 227                 return $serializationData;
 228         }
 229
 230         /**
 231          * Returns if the ArrayObject has no elements.
 232          *
 233          * @since 1.20
 234          *
 235          * @return boolean
 236          */
 237         public function isEmpty() {
 238                 return $this->count() === 0;
 239         }
 240
 241 }