[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Blocks API: WP_Block_List class
   4   *
   5   * @package WordPress
   6   * @since 5.5.0
   7   */
   8  
   9  /**
  10   * Class representing a list of block instances.
  11   *
  12   * @since 5.5.0
  13   */
  14  class WP_Block_List implements Iterator, ArrayAccess, Countable {
  15  
  16      /**
  17       * Original array of parsed block data, or block instances.
  18       *
  19       * @since 5.5.0
  20       * @var array[]|WP_Block[]
  21       * @access protected
  22       */
  23      protected $blocks;
  24  
  25      /**
  26       * All available context of the current hierarchy.
  27       *
  28       * @since 5.5.0
  29       * @var array
  30       * @access protected
  31       */
  32      protected $available_context;
  33  
  34      /**
  35       * Block type registry to use in constructing block instances.
  36       *
  37       * @since 5.5.0
  38       * @var WP_Block_Type_Registry
  39       * @access protected
  40       */
  41      protected $registry;
  42  
  43      /**
  44       * Constructor.
  45       *
  46       * Populates object properties from the provided block instance argument.
  47       *
  48       * @since 5.5.0
  49       *
  50       * @param array[]|WP_Block[]     $blocks            Array of parsed block data, or block instances.
  51       * @param array                  $available_context Optional array of ancestry context values.
  52       * @param WP_Block_Type_Registry $registry          Optional block type registry.
  53       */
  54  	public function __construct( $blocks, $available_context = array(), $registry = null ) {
  55          if ( ! $registry instanceof WP_Block_Type_Registry ) {
  56              $registry = WP_Block_Type_Registry::get_instance();
  57          }
  58  
  59          $this->blocks            = $blocks;
  60          $this->available_context = $available_context;
  61          $this->registry          = $registry;
  62      }
  63  
  64      /**
  65       * Returns true if a block exists by the specified block index, or false
  66       * otherwise.
  67       *
  68       * @since 5.5.0
  69       *
  70       * @link https://www.php.net/manual/en/arrayaccess.offsetexists.php
  71       *
  72       * @param string $index Index of block to check.
  73       * @return bool Whether block exists.
  74       */
  75      #[ReturnTypeWillChange]
  76  	public function offsetExists( $index ) {
  77          return isset( $this->blocks[ $index ] );
  78      }
  79  
  80      /**
  81       * Returns the value by the specified block index.
  82       *
  83       * @since 5.5.0
  84       *
  85       * @link https://www.php.net/manual/en/arrayaccess.offsetget.php
  86       *
  87       * @param string $index Index of block value to retrieve.
  88       * @return mixed|null Block value if exists, or null.
  89       */
  90      #[ReturnTypeWillChange]
  91  	public function offsetGet( $index ) {
  92          $block = $this->blocks[ $index ];
  93  
  94          if ( isset( $block ) && is_array( $block ) ) {
  95              $block                  = new WP_Block( $block, $this->available_context, $this->registry );
  96              $this->blocks[ $index ] = $block;
  97          }
  98  
  99          return $block;
 100      }
 101  
 102      /**
 103       * Assign a block value by the specified block index.
 104       *
 105       * @since 5.5.0
 106       *
 107       * @link https://www.php.net/manual/en/arrayaccess.offsetset.php
 108       *
 109       * @param string $index Index of block value to set.
 110       * @param mixed  $value Block value.
 111       */
 112      #[ReturnTypeWillChange]
 113  	public function offsetSet( $index, $value ) {
 114          if ( is_null( $index ) ) {
 115              $this->blocks[] = $value;
 116          } else {
 117              $this->blocks[ $index ] = $value;
 118          }
 119      }
 120  
 121      /**
 122       * Unset a block.
 123       *
 124       * @since 5.5.0
 125       *
 126       * @link https://www.php.net/manual/en/arrayaccess.offsetunset.php
 127       *
 128       * @param string $index Index of block value to unset.
 129       */
 130      #[ReturnTypeWillChange]
 131  	public function offsetUnset( $index ) {
 132          unset( $this->blocks[ $index ] );
 133      }
 134  
 135      /**
 136       * Rewinds back to the first element of the Iterator.
 137       *
 138       * @since 5.5.0
 139       *
 140       * @link https://www.php.net/manual/en/iterator.rewind.php
 141       */
 142      #[ReturnTypeWillChange]
 143  	public function rewind() {
 144          reset( $this->blocks );
 145      }
 146  
 147      /**
 148       * Returns the current element of the block list.
 149       *
 150       * @since 5.5.0
 151       *
 152       * @link https://www.php.net/manual/en/iterator.current.php
 153       *
 154       * @return mixed Current element.
 155       */
 156      #[ReturnTypeWillChange]
 157  	public function current() {
 158          return $this->offsetGet( $this->key() );
 159      }
 160  
 161      /**
 162       * Returns the key of the current element of the block list.
 163       *
 164       * @since 5.5.0
 165       *
 166       * @link https://www.php.net/manual/en/iterator.key.php
 167       *
 168       * @return mixed Key of the current element.
 169       */
 170      #[ReturnTypeWillChange]
 171  	public function key() {
 172          return key( $this->blocks );
 173      }
 174  
 175      /**
 176       * Moves the current position of the block list to the next element.
 177       *
 178       * @since 5.5.0
 179       *
 180       * @link https://www.php.net/manual/en/iterator.next.php
 181       */
 182      #[ReturnTypeWillChange]
 183  	public function next() {
 184          next( $this->blocks );
 185      }
 186  
 187      /**
 188       * Checks if current position is valid.
 189       *
 190       * @since 5.5.0
 191       *
 192       * @link https://www.php.net/manual/en/iterator.valid.php
 193       */
 194      #[ReturnTypeWillChange]
 195  	public function valid() {
 196          return null !== key( $this->blocks );
 197      }
 198  
 199      /**
 200       * Returns the count of blocks in the list.
 201       *
 202       * @since 5.5.0
 203       *
 204       * @link https://www.php.net/manual/en/countable.count.php
 205       *
 206       * @return int Block count.
 207       */
 208      #[ReturnTypeWillChange]
 209  	public function count() {
 210          return count( $this->blocks );
 211      }
 212  
 213  }