Chris@5: <?php
Chris@5: 
Chris@5: namespace Drupal\jsonapi\Revisions;
Chris@5: 
Chris@5: use Drupal\Core\Cache\CacheableMetadata;
Chris@5: use Drupal\Core\Entity\EntityInterface;
Chris@5: use Drupal\Core\Http\Exception\CacheableBadRequestHttpException;
Chris@5: use Drupal\Core\Http\Exception\CacheableNotFoundHttpException;
Chris@5: 
Chris@5: /**
Chris@5:  * Provides a version negotiator manager.
Chris@5:  *
Chris@5:  * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@5:  *   class may change at any time and this will break any dependencies on it.
Chris@5:  *
Chris@5:  * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@5:  * @see jsonapi.api.php
Chris@5:  *
Chris@5:  * @see \Drupal\jsonapi\Revisions\VersionNegotiatorInterface
Chris@5:  */
Chris@5: class VersionNegotiator {
Chris@5: 
Chris@5:   /**
Chris@5:    * The separator between the version negotiator name and the version argument.
Chris@5:    *
Chris@5:    * @var string
Chris@5:    */
Chris@5:   const SEPARATOR = ':';
Chris@5: 
Chris@5:   /**
Chris@5:    * An array of named version negotiators.
Chris@5:    *
Chris@5:    * @var \Drupal\jsonapi\Revisions\VersionNegotiatorInterface[]
Chris@5:    */
Chris@5:   protected $negotiators = [];
Chris@5: 
Chris@5:   /**
Chris@5:    * Adds a version negotiator.
Chris@5:    *
Chris@5:    * @param \Drupal\jsonapi\Revisions\VersionNegotiatorInterface $version_negotiator
Chris@5:    *   The version negotiator.
Chris@5:    * @param string $negotiator_name
Chris@5:    *   The name of the negotiation strategy used by the version negotiator.
Chris@5:    */
Chris@5:   public function addVersionNegotiator(VersionNegotiatorInterface $version_negotiator, $negotiator_name) {
Chris@5:     assert(strpos(get_class($version_negotiator), 'Drupal\\jsonapi\\') === 0, 'Version negotiators are not a public API.');
Chris@5:     $this->negotiators[$negotiator_name] = $version_negotiator;
Chris@5:   }
Chris@5: 
Chris@5:   /**
Chris@5:    * Gets a negotiated entity revision.
Chris@5:    *
Chris@5:    * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@5:    *   The entity.
Chris@5:    * @param string $resource_version_identifier
Chris@5:    *   A value used to derive a revision for the given entity.
Chris@5:    *
Chris@5:    * @return \Drupal\Core\Entity\EntityInterface
Chris@5:    *   The loaded revision.
Chris@5:    *
Chris@5:    * @throws \Drupal\Core\Http\Exception\CacheableNotFoundHttpException
Chris@5:    *   When the revision does not exist.
Chris@5:    * @throws \Drupal\Core\Http\Exception\CacheableBadRequestHttpException
Chris@5:    *   When the revision ID cannot be negotiated.
Chris@5:    */
Chris@5:   public function getRevision(EntityInterface $entity, $resource_version_identifier) {
Chris@5:     try {
Chris@5:       list($version_negotiator_name, $version_argument) = explode(VersionNegotiator::SEPARATOR, $resource_version_identifier, 2);
Chris@5:       if (!isset($this->negotiators[$version_negotiator_name])) {
Chris@5:         static::throwBadRequestHttpException($resource_version_identifier);
Chris@5:       }
Chris@5:       return $this->negotiators[$version_negotiator_name]->getRevision($entity, $version_argument);
Chris@5:     }
Chris@5:     catch (VersionNotFoundException $exception) {
Chris@5:       static::throwNotFoundHttpException($entity, $resource_version_identifier);
Chris@5:     }
Chris@5:     catch (InvalidVersionIdentifierException $exception) {
Chris@5:       static::throwBadRequestHttpException($resource_version_identifier);
Chris@5:     }
Chris@5:   }
Chris@5: 
Chris@5:   /**
Chris@5:    * Throws a cacheable error exception.
Chris@5:    *
Chris@5:    * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@5:    *   The entity for which a revision was requested.
Chris@5:    * @param string $resource_version_identifier
Chris@5:    *   The user input for the revision negotiation.
Chris@5:    *
Chris@5:    * @throws \Drupal\Core\Http\Exception\CacheableNotFoundHttpException
Chris@5:    */
Chris@5:   protected static function throwNotFoundHttpException(EntityInterface $entity, $resource_version_identifier) {
Chris@5:     $cacheability = CacheableMetadata::createFromObject($entity)->addCacheContexts(['url.path', 'url.query_args:' . ResourceVersionRouteEnhancer::RESOURCE_VERSION_QUERY_PARAMETER]);
Chris@5:     $reason = sprintf('The requested version, identified by `%s`, could not be found.', $resource_version_identifier);
Chris@5:     throw new CacheableNotFoundHttpException($cacheability, $reason);
Chris@5:   }
Chris@5: 
Chris@5:   /**
Chris@5:    * Throws a cacheable error exception.
Chris@5:    *
Chris@5:    * @param string $resource_version_identifier
Chris@5:    *   The user input for the revision negotiation.
Chris@5:    *
Chris@5:    * @throws \Drupal\Core\Http\Exception\CacheableBadRequestHttpException
Chris@5:    */
Chris@5:   protected static function throwBadRequestHttpException($resource_version_identifier) {
Chris@5:     $cacheability = (new CacheableMetadata())->addCacheContexts(['url.query_args:' . ResourceVersionRouteEnhancer::RESOURCE_VERSION_QUERY_PARAMETER]);
Chris@5:     $message = sprintf('An invalid resource version identifier, `%s`, was provided.', $resource_version_identifier);
Chris@5:     throw new CacheableBadRequestHttpException($cacheability, $message);
Chris@5:   }
Chris@5: 
Chris@5: }