?<?php
/**
 * Blocks API: WP_Block_List class
 *
 * @package WordPress
 * @since 5.5.0
 */

/**
 * Class representing a list of block instances.
 *
 * @since 5.5.0
 */
#[AllowDynamicProperties]
class WP_Block_List implements Iterator, ArrayAccess, Countable {

	/**
	 * Original array of parsed block data, or block instances.
	 *
	 * @since 5.5.0
	 * @var array[]|WP_Block[]
	 * @access protected
	 */
	protected $blocks;

	/**
	 * All available context of the current hierarchy.
	 *
	 * @since 5.5.0
	 * @var array
	 * @access protected
	 */
	protected $available_context;

	/**
	 * Block type registry to use in constructing block instances.
	 *
	 * @since 5.5.0
	 * @var WP_Block_Type_Registry
	 * @access protected
	 */
	protected $registry;

	/**
	 * Constructor.
	 *
	 * Populates object properties from the provided block instance argument.
	 *
	 * @since 5.5.0
	 *
	 * @param array[]|WP_Block[]     $blocks            Array of parsed block data, or block instances.
	 * @param array                  $available_context Optional array of ancestry context values.
	 * @param WP_Block_Type_Registry $registry          Optional block type registry.
	 */
	public function __construct( $blocks, $available_context = array(), $registry = null ) {
		if ( ! $registry instanceof WP_Block_Type_Registry ) {
			$registry = WP_Block_Type_Registry::get_instance();
		}

		$this->blocks            = $blocks;
		$this->available_context = $available_context;
		$this->registry          = $registry;
	}

	/**
	 * Returns true if a block exists by the specified block offset, or false
	 * otherwise.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/arrayaccess.offsetexists.php
	 *
	 * @param string $offset Offset of block to check for.
	 * @return bool Whether block exists.
	 */
	#[ReturnTypeWillChange]
	public function offsetExists( $offset ) {
		return isset( $this->blocks[ $offset ] );
	}

	/**
	 * Returns the value by the specified block offset.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/arrayaccess.offsetget.php
	 *
	 * @param string $offset Offset of block value to retrieve.
	 * @return mixed|null Block value if exists, or null.
	 */
	#[ReturnTypeWillChange]
	public function offsetGet( $offset ) {
		$block = $this->blocks[ $offset ];

		if ( isset( $block ) && is_array( $block ) ) {
			$block = new WP_Block( $block, $this->available_context, $this->registry );

			$this->blocks[ $offset ] = $block;
		}

		return $block;
	}

	/**
	 * Assign a block value by the specified block offset.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/arrayaccess.offsetset.php
	 *
	 * @param string $offset Offset of block value to set.
	 * @param mixed  $value Block value.
	 */
	#[ReturnTypeWillChange]
	public function offsetSet( $offset, $value ) {
		if ( is_null( $offset ) ) {
			$this->blocks[] = $value;
		} else {
			$this->blocks[ $offset ] = $value;
		}
	}

	/**
	 * Unset a block.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/arrayaccess.offsetunset.php
	 *
	 * @param string $offset Offset of block value to unset.
	 */
	#[ReturnTypeWillChange]
	public function offsetUnset( $offset ) {
		unset( $this->blocks[ $offset ] );
	}

	/**
	 * Rewinds back to the first element of the Iterator.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/iterator.rewind.php
	 */
	#[ReturnTypeWillChange]
	public function rewind() {
		reset( $this->blocks );
	}

	/**
	 * Returns the current element of the block list.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/iterator.current.php
	 *
	 * @return mixed Current element.
	 */
	#[ReturnTypeWillChange]
	public function current() {
		return $this->offsetGet( $this->key() );
	}

	/**
	 * Returns the key of the current element of the block list.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/iterator.key.php
	 *
	 * @return mixed Key of the current element.
	 */
	#[ReturnTypeWillChange]
	public function key() {
		return key( $this->blocks );
	}

	/**
	 * Moves the current position of the block list to the next element.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/iterator.next.php
	 */
	#[ReturnTypeWillChange]
	public function next() {
		next( $this->blocks );
	}

	/**
	 * Checks if current position is valid.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/iterator.valid.php
	 */
	#[ReturnTypeWillChange]
	public function valid() {
		return null !== key( $this->blocks );
	}

	/**
	 * Returns the count of blocks in the list.
	 *
	 * @since 5.5.0
	 *
	 * @link https://www.php.net/manual/en/countable.count.php
	 *
	 * @return int Block count.
	 */
	#[ReturnTypeWillChange]
	public function count() {
		return count( $this->blocks );
	}
}