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