<?php

namespace Drupal\Core\Database;

/**
 * StatementInterface iterator trait.
 *
 * Implements the methods required by StatementInterface objects that implement
 * the \Iterator interface.
 */
trait StatementIteratorTrait {

  /**
   * Traces if rows can be fetched from the resultset.
   */
  private bool $isResultsetIterable = FALSE;

  /**
   * The current row, retrieved in the current fetch format.
   */
  private mixed $resultsetRow = NULL;

  /**
   * The key of the current row.
   *
   * This keeps the index of rows fetched from the underlying statement. It is
   * set to -1 when no rows have been fetched yet.
   */
  private int $resultsetKey = -1;

  /**
   * Informs the iterator whether rows can be fetched from the resultset.
   *
   * @param bool $valid
   *   The result of the execution of the client statement.
   */
  protected function markResultsetIterable(bool $valid): void {
    $this->isResultsetIterable = $valid;
    $this->resultsetRow = NULL;
    if ($valid === TRUE) {
      $this->resultsetKey = -1;
    }
  }

  /**
   * Sets the current resultset row for the iterator, and increments the key.
   *
   * @param mixed $row
   *   The last row fetched from the client statement.
   */
  protected function setResultsetCurrentRow(mixed $row): void {
    $this->resultsetRow = $row;
    $this->resultsetKey++;
  }

  /**
   * Returns the row index of the current element in the resultset.
   *
   * @return int
   *   The row index of the current element in the resultset.
   */
  protected function getResultsetCurrentRowIndex(): int {
    return $this->resultsetKey;
  }

  /**
   * Informs the iterator that no more rows can be fetched from the resultset.
   */
  protected function markResultsetFetchingComplete(): void {
    $this->markResultsetIterable(FALSE);
  }

  /**
   * Returns the current element.
   *
   * @see https://www.php.net/manual/en/iterator.current.php
   *
   * @internal This method should not be called directly.
   */
  public function current(): mixed {
    return $this->resultsetRow;
  }

  /**
   * Returns the key of the current element.
   *
   * @see https://www.php.net/manual/en/iterator.key.php
   *
   * @internal This method should not be called directly.
   */
  public function key(): mixed {
    return $this->resultsetKey;
  }

  /**
   * Rewinds back to the first element of the Iterator.
   *
   * This is the first method called when starting a foreach loop. It will not
   * be executed after foreach loops.
   *
   * @see https://www.php.net/manual/en/iterator.rewind.php
   *
   * @internal This method should not be called directly.
   */
  public function rewind(): void {
    // Nothing to do: our DatabaseStatement can't be rewound. Error out when
    // attempted.
    if ($this->resultsetKey >= 0) {
      $this->markResultsetIterable(FALSE);
      throw new DatabaseExceptionWrapper('Attempted rewinding a StatementInterface object when fetching has already started. Refactor your code to avoid rewinding statement objects.');
    }
  }

  /**
   * Moves the current position to the next element.
   *
   * This method is called after each foreach loop.
   *
   * @see https://www.php.net/manual/en/iterator.next.php
   *
   * @internal This method should not be called directly.
   */
  public function next(): void {
    $this->fetch();
  }

  /**
   * Checks if current position is valid.
   *
   * This method is called after ::rewind() and ::next() to check if the
   * current position is valid.
   *
   * @see https://www.php.net/manual/en/iterator.valid.php
   *
   * @internal This method should not be called directly.
   */
  public function valid(): bool {
    if ($this->isResultsetIterable && $this->resultsetKey === -1) {
      $this->fetch();
    }
    return $this->isResultsetIterable;
  }

}