annotate core/modules/jsonapi/src/Revisions/NegotiatorBase.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@18 1 <?php
Chris@18 2
Chris@18 3 namespace Drupal\jsonapi\Revisions;
Chris@18 4
Chris@18 5 use Drupal\Core\Entity\EntityInterface;
Chris@18 6 use Drupal\Core\Entity\EntityTypeManagerInterface;
Chris@18 7
Chris@18 8 /**
Chris@18 9 * Base implementation for version negotiators.
Chris@18 10 *
Chris@18 11 * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@18 12 * class may change at any time and this will break any dependencies on it.
Chris@18 13 *
Chris@18 14 * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18 15 * @see jsonapi.api.php
Chris@18 16 */
Chris@18 17 abstract class NegotiatorBase implements VersionNegotiatorInterface {
Chris@18 18
Chris@18 19 /**
Chris@18 20 * The entity type manager to load the revision.
Chris@18 21 *
Chris@18 22 * @var \Drupal\Core\Entity\EntityTypeManagerInterface
Chris@18 23 */
Chris@18 24 protected $entityTypeManager;
Chris@18 25
Chris@18 26 /**
Chris@18 27 * Constructs a version negotiator instance.
Chris@18 28 *
Chris@18 29 * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
Chris@18 30 * The entity type manager.
Chris@18 31 */
Chris@18 32 public function __construct(EntityTypeManagerInterface $entity_type_manager) {
Chris@18 33 $this->entityTypeManager = $entity_type_manager;
Chris@18 34 }
Chris@18 35
Chris@18 36 /**
Chris@18 37 * Gets the revision ID.
Chris@18 38 *
Chris@18 39 * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@18 40 * The entity.
Chris@18 41 * @param string $version_argument
Chris@18 42 * A value used to derive a revision ID for the given entity.
Chris@18 43 *
Chris@18 44 * @return int
Chris@18 45 * The revision ID.
Chris@18 46 *
Chris@18 47 * @throws \Drupal\jsonapi\Revisions\VersionNotFoundException
Chris@18 48 * When the revision does not exist.
Chris@18 49 * @throws \Drupal\jsonapi\Revisions\InvalidVersionIdentifierException
Chris@18 50 * When the revision ID is not valid.
Chris@18 51 */
Chris@18 52 abstract protected function getRevisionId(EntityInterface $entity, $version_argument);
Chris@18 53
Chris@18 54 /**
Chris@18 55 * {@inheritdoc}
Chris@18 56 */
Chris@18 57 public function getRevision(EntityInterface $entity, $version_argument) {
Chris@18 58 return $this->loadRevision($entity, $this->getRevisionId($entity, $version_argument));
Chris@18 59 }
Chris@18 60
Chris@18 61 /**
Chris@18 62 * Loads an entity revision.
Chris@18 63 *
Chris@18 64 * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@18 65 * The entity for which to load a revision.
Chris@18 66 * @param int $revision_id
Chris@18 67 * The revision ID to be loaded.
Chris@18 68 *
Chris@18 69 * @return \Drupal\Core\Entity\EntityInterface|null
Chris@18 70 * The revision or NULL if the revision does not exists.
Chris@18 71 *
Chris@18 72 * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
Chris@18 73 * Thrown if the entity type doesn't exist.
Chris@18 74 * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
Chris@18 75 * Thrown if the storage handler couldn't be loaded.
Chris@18 76 */
Chris@18 77 protected function loadRevision(EntityInterface $entity, $revision_id) {
Chris@18 78 $storage = $this->entityTypeManager->getStorage($entity->getEntityTypeId());
Chris@18 79 $revision = static::ensureVersionExists($storage->loadRevision($revision_id));
Chris@18 80 if ($revision->id() !== $entity->id()) {
Chris@18 81 throw new VersionNotFoundException(sprintf('The requested resource does not have a version with ID %s.', $revision_id));
Chris@18 82 }
Chris@18 83 return $revision;
Chris@18 84 }
Chris@18 85
Chris@18 86 /**
Chris@18 87 * Helper method that ensures that a version exists.
Chris@18 88 *
Chris@18 89 * @param int|\Drupal\Core\Entity\EntityInterface $revision
Chris@18 90 * A revision ID, or NULL if one was not found.
Chris@18 91 *
Chris@18 92 * @return int|\Drupal\Core\Entity\EntityInterface
Chris@18 93 * A revision or revision ID, if one was found.
Chris@18 94 *
Chris@18 95 * @throws \Drupal\jsonapi\Revisions\VersionNotFoundException
Chris@18 96 * Thrown if the given value is NULL, meaning the requested version was not
Chris@18 97 * found.
Chris@18 98 */
Chris@18 99 protected static function ensureVersionExists($revision) {
Chris@18 100 if (is_null($revision)) {
Chris@18 101 throw new VersionNotFoundException();
Chris@18 102 }
Chris@18 103 return $revision;
Chris@18 104 }
Chris@18 105
Chris@18 106 }