CheckpointListInterface.php

<?php

declare (strict_types=1);
namespace Drupal\Core\Config\Checkpoint;


/**
 * Maintains a list of checkpoints.
 *
 * @internal
 *   This API is experimental.
 *
 * @see \Drupal\Core\Config\Checkpoint\Checkpoint
 *
 * @phpstan-extends \IteratorAggregate<string, \Drupal\Core\Config\Checkpoint\Checkpoint>
 */
interface CheckpointListInterface extends \IteratorAggregate, \Countable {
    
    /**
     * Gets the active checkpoint.
     *
     * @return \Drupal\Core\Config\Checkpoint\Checkpoint|null
     *   The active checkpoint or NULL if there are no checkpoints.
     */
    public function getActiveCheckpoint() : ?Checkpoint;
    
    /**
     * Gets a checkpoint.
     *
     * @param string $id
     *   The checkpoint ID.
     *
     * @return \Drupal\Core\Config\Checkpoint\Checkpoint
     *   The checkpoint.
     *
     * @throws \Drupal\Core\Config\Checkpoint\UnknownCheckpointException
     *   Thrown when the provided checkpoint does not exist.
     */
    public function get(string $id) : Checkpoint;
    
    /**
     * Gets a checkpoint's parents.
     *
     * @param string $id
     *   The checkpoint ID.
     *
     * @return iterable<string, \Drupal\Core\Config\Checkpoint\Checkpoint>
     */
    public function getParents(string $id) : iterable;
    
    /**
     * Adds a new checkpoint.
     *
     * @param string $id
     *   The ID of the checkpoint add.
     * @param string|\Stringable $label
     *   The checkpoint label.
     *
     * @return \Drupal\Core\Config\Checkpoint\Checkpoint
     *   The new checkpoint, which is now at the end of the checkpoint sequence.
     *
     * @throws \Drupal\Core\Config\Checkpoint\CheckpointExistsException
     *   Thrown when the ID already exists.
     */
    public function add(string $id, string|\Stringable $label) : Checkpoint;
    
    /**
     * Deletes a checkpoint.
     *
     * @param string $id
     *   The ID of the checkpoint to delete up to: only checkpoints after this one
     *   will remain.
     *
     * @return $this
     *
     * @throws \Drupal\Core\Config\Checkpoint\UnknownCheckpointException
     *   Thrown when provided checkpoint ID does not exist.
     */
    public function delete(string $id) : static;
    
    /**
     * Deletes all checkpoints.
     *
     * @return $this
     */
    public function deleteAll() : static;

}