RevisionableInterface.php 3.31 KB
Newer Older
1 2 3 4 5 6
<?php

namespace Drupal\Core\Entity;

/**
 * Provides methods for an entity to support revisions.
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
 *
 * Classes implementing this interface do not necessarily support revisions.
 *
 * To detect whether an entity type supports revisions, call
 * EntityTypeInterface::isRevisionable().
 *
 * Many entity interfaces are composed of numerous other interfaces such as this
 * one, which allow implementations to pick and choose which features to.
 * support through stub implementations of various interface methods. This means
 * that even if an entity class implements RevisionableInterface, it might only
 * have a stub implementation and not a functional one.
 *
 * @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable()
 * @see https://www.drupal.org/docs/8/api/entity-api/structure-of-an-entity-annotation
 * @see https://www.drupal.org/docs/8/api/entity-api/making-an-entity-revisionable
22 23 24 25
 */
interface RevisionableInterface {

  /**
26
   * Determines whether a new revision should be created on save.
27 28 29 30 31 32 33 34 35 36 37 38 39 40
   *
   * @return bool
   *   TRUE if a new revision should be created.
   *
   * @see \Drupal\Core\Entity\EntityInterface::setNewRevision()
   */
  public function isNewRevision();

  /**
   * Enforces an entity to be saved as a new revision.
   *
   * @param bool $value
   *   (optional) Whether a new revision should be saved.
   *
41 42 43
   * @throws \LogicException
   *   Thrown if the entity does not support revisions.
   *
44 45 46 47 48
   * @see \Drupal\Core\Entity\EntityInterface::isNewRevision()
   */
  public function setNewRevision($value = TRUE);

  /**
49
   * Gets the revision identifier of the entity.
50 51 52 53 54 55 56
   *
   * @return
   *   The revision identifier of the entity, or NULL if the entity does not
   *   have a revision identifier.
   */
  public function getRevisionId();

57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
  /**
   * Gets the loaded Revision ID of the entity.
   *
   * @return int
   *   The loaded Revision identifier of the entity, or NULL if the entity
   *   does not have a revision identifier.
   */
  public function getLoadedRevisionId();

  /**
   * Updates the loaded Revision ID with the revision ID.
   *
   * This method should not be used, it could unintentionally cause the original
   * revision ID property value to be lost.
   *
   * @internal
   *
   * @return $this
   */
  public function updateLoadedRevisionId();

78 79 80 81 82 83 84 85 86 87 88 89
  /**
   * Checks if this entity is the default revision.
   *
   * @param bool $new_value
   *   (optional) A Boolean to (re)set the isDefaultRevision flag.
   *
   * @return bool
   *   TRUE if the entity is the default revision, FALSE otherwise. If
   *   $new_value was passed, the previous value is returned.
   */
  public function isDefaultRevision($new_value = NULL);

90 91 92 93 94 95 96 97
  /**
   * Checks whether the entity object was a default revision when it was saved.
   *
   * @return bool
   *   TRUE if the entity object was a revision, FALSE otherwise.
   */
  public function wasDefaultRevision();

98 99 100 101 102 103 104 105
  /**
   * Checks if this entity is the latest revision.
   *
   * @return bool
   *   TRUE if the entity is the latest revision, FALSE otherwise.
   */
  public function isLatestRevision();

106 107 108
  /**
   * Acts on a revision before it gets saved.
   *
109 110
   * @param EntityStorageInterface $storage
   *   The entity storage object.
111 112 113
   * @param \stdClass $record
   *   The revision object.
   */
114
  public function preSaveRevision(EntityStorageInterface $storage, \stdClass $record);
115 116

}