class VersionNegotiator
Same name in other branches
- 9 core/modules/jsonapi/src/Revisions/VersionNegotiator.php \Drupal\jsonapi\Revisions\VersionNegotiator
- 8.9.x core/modules/jsonapi/src/Revisions/VersionNegotiator.php \Drupal\jsonapi\Revisions\VersionNegotiator
- 11.x core/modules/jsonapi/src/Revisions/VersionNegotiator.php \Drupal\jsonapi\Revisions\VersionNegotiator
Provides a version negotiator manager.
@internal JSON:API maintains no PHP API since its API is the HTTP API. This class may change at any time and this will break any dependencies on it.
Hierarchy
- class \Drupal\jsonapi\Revisions\VersionNegotiator
Expanded class hierarchy of VersionNegotiator
See also
https://www.drupal.org/project/drupal/issues/3032787
\Drupal\jsonapi\Revisions\VersionNegotiatorInterface
1 file declares its use of VersionNegotiator
- VersionNegotiatorTest.php in core/
modules/ jsonapi/ tests/ src/ Kernel/ Revisions/ VersionNegotiatorTest.php
1 string reference to 'VersionNegotiator'
- jsonapi.services.yml in core/
modules/ jsonapi/ jsonapi.services.yml - core/modules/jsonapi/jsonapi.services.yml
1 service uses VersionNegotiator
- jsonapi.version_negotiator in core/
modules/ jsonapi/ jsonapi.services.yml - Drupal\jsonapi\Revisions\VersionNegotiator
File
-
core/
modules/ jsonapi/ src/ Revisions/ VersionNegotiator.php, line 21
Namespace
Drupal\jsonapi\RevisionsView source
class VersionNegotiator {
/**
* The separator between the version negotiator name and the version argument.
*
* @var string
*/
const SEPARATOR = ':';
/**
* An array of named version negotiators.
*
* @var \Drupal\jsonapi\Revisions\VersionNegotiatorInterface[]
*/
protected $negotiators = [];
/**
* Adds a version negotiator.
*
* @param \Drupal\jsonapi\Revisions\VersionNegotiatorInterface $version_negotiator
* The version negotiator.
* @param string $negotiator_name
* The name of the negotiation strategy used by the version negotiator.
*/
public function addVersionNegotiator(VersionNegotiatorInterface $version_negotiator, $negotiator_name) {
assert(str_starts_with(get_class($version_negotiator), 'Drupal\\jsonapi\\'), 'Version negotiators are not a public API.');
$this->negotiators[$negotiator_name] = $version_negotiator;
}
/**
* Gets a negotiated entity revision.
*
* @param \Drupal\Core\Entity\EntityInterface $entity
* The entity.
* @param string $resource_version_identifier
* A value used to derive a revision for the given entity.
*
* @return \Drupal\Core\Entity\EntityInterface
* The loaded revision.
*
* @throws \Drupal\Core\Http\Exception\CacheableNotFoundHttpException
* When the revision does not exist.
* @throws \Drupal\Core\Http\Exception\CacheableBadRequestHttpException
* When the revision ID cannot be negotiated.
*/
public function getRevision(EntityInterface $entity, $resource_version_identifier) {
try {
[
$version_negotiator_name,
$version_argument,
] = explode(VersionNegotiator::SEPARATOR, $resource_version_identifier, 2);
if (!isset($this->negotiators[$version_negotiator_name])) {
static::throwBadRequestHttpException($resource_version_identifier);
}
return $this->negotiators[$version_negotiator_name]
->getRevision($entity, $version_argument);
} catch (VersionNotFoundException $exception) {
static::throwNotFoundHttpException($entity, $resource_version_identifier);
} catch (InvalidVersionIdentifierException $exception) {
static::throwBadRequestHttpException($resource_version_identifier);
}
}
/**
* Throws a cacheable error exception.
*
* @param \Drupal\Core\Entity\EntityInterface $entity
* The entity for which a revision was requested.
* @param string $resource_version_identifier
* The user input for the revision negotiation.
*
* @throws \Drupal\Core\Http\Exception\CacheableNotFoundHttpException
*/
protected static function throwNotFoundHttpException(EntityInterface $entity, $resource_version_identifier) {
$cacheability = CacheableMetadata::createFromObject($entity)->addCacheContexts([
'url.path',
'url.query_args:' . ResourceVersionRouteEnhancer::RESOURCE_VERSION_QUERY_PARAMETER,
]);
$reason = sprintf('The requested version, identified by `%s`, could not be found.', $resource_version_identifier);
throw new CacheableNotFoundHttpException($cacheability, $reason);
}
/**
* Throws a cacheable error exception.
*
* @param string $resource_version_identifier
* The user input for the revision negotiation.
*
* @throws \Drupal\Core\Http\Exception\CacheableBadRequestHttpException
*/
protected static function throwBadRequestHttpException($resource_version_identifier) {
$cacheability = (new CacheableMetadata())->addCacheContexts([
'url.query_args:' . ResourceVersionRouteEnhancer::RESOURCE_VERSION_QUERY_PARAMETER,
]);
$message = sprintf('An invalid resource version identifier, `%s`, was provided.', $resource_version_identifier);
throw new CacheableBadRequestHttpException($cacheability, $message);
}
}
Members
Title Sort descending | Modifiers | Object type | Summary |
---|---|---|---|
VersionNegotiator::$negotiators | protected | property | An array of named version negotiators. |
VersionNegotiator::addVersionNegotiator | public | function | Adds a version negotiator. |
VersionNegotiator::getRevision | public | function | Gets a negotiated entity revision. |
VersionNegotiator::SEPARATOR | constant | The separator between the version negotiator name and the version argument. | |
VersionNegotiator::throwBadRequestHttpException | protected static | function | Throws a cacheable error exception. |
VersionNegotiator::throwNotFoundHttpException | protected static | function | Throws a cacheable error exception. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.