annotate core/modules/jsonapi/src/JsonApiResource/ResourceIdentifier.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\JsonApiResource;
Chris@18 4
Chris@18 5 use Drupal\Core\Entity\EntityInterface;
Chris@18 6 use Drupal\Core\Field\EntityReferenceFieldItemListInterface;
Chris@18 7 use Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem;
Chris@18 8 use Drupal\Core\TypedData\DataReferenceDefinitionInterface;
Chris@18 9 use Drupal\Core\TypedData\TypedDataInternalPropertiesHelper;
Chris@18 10 use Drupal\jsonapi\ResourceType\ResourceType;
Chris@18 11
Chris@18 12 /**
Chris@18 13 * Represents a JSON:API resource identifier object.
Chris@18 14 *
Chris@18 15 * The official JSON:API JSON-Schema document requires that no two resource
Chris@18 16 * identifier objects are duplicates, however Drupal allows multiple entity
Chris@18 17 * reference items to the same entity. Here, these are termed "parallel"
Chris@18 18 * relationships (as in "parallel edges" of a graph).
Chris@18 19 *
Chris@18 20 * This class adds a concept of an @code arity @endcode member under each its
Chris@18 21 * @code meta @endcode object. The value of this member is an integer that is
Chris@18 22 * incremented by 1 (starting from 0) for each repeated resource identifier
Chris@18 23 * sharing a common @code type @endcode and @code id @endcode.
Chris@18 24 *
Chris@18 25 * There are a number of helper methods to process the logic of dealing with
Chris@18 26 * resource identifies with and without arity.
Chris@18 27 *
Chris@18 28 * @internal JSON:API maintains no PHP API. The API is the HTTP API. This class
Chris@18 29 * may change at any time and could break any dependencies on it.
Chris@18 30 *
Chris@18 31 * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18 32 * @see jsonapi.api.php
Chris@18 33 *
Chris@18 34 * @see http://jsonapi.org/format/#document-resource-object-relationships
Chris@18 35 * @see https://github.com/json-api/json-api/pull/1156#issuecomment-325377995
Chris@18 36 * @see https://www.drupal.org/project/jsonapi/issues/2864680
Chris@18 37 */
Chris@18 38 class ResourceIdentifier implements ResourceIdentifierInterface {
Chris@18 39
Chris@18 40 const ARITY_KEY = 'arity';
Chris@18 41
Chris@18 42 /**
Chris@18 43 * The JSON:API resource type name.
Chris@18 44 *
Chris@18 45 * @var string
Chris@18 46 */
Chris@18 47 protected $resourceTypeName;
Chris@18 48
Chris@18 49 /**
Chris@18 50 * The JSON:API resource type.
Chris@18 51 *
Chris@18 52 * @var \Drupal\jsonapi\ResourceType\ResourceType
Chris@18 53 */
Chris@18 54 protected $resourceType;
Chris@18 55
Chris@18 56 /**
Chris@18 57 * The resource ID.
Chris@18 58 *
Chris@18 59 * @var string
Chris@18 60 */
Chris@18 61 protected $id;
Chris@18 62
Chris@18 63 /**
Chris@18 64 * The relationship's metadata.
Chris@18 65 *
Chris@18 66 * @var array
Chris@18 67 */
Chris@18 68 protected $meta;
Chris@18 69
Chris@18 70 /**
Chris@18 71 * ResourceIdentifier constructor.
Chris@18 72 *
Chris@18 73 * @param \Drupal\jsonapi\ResourceType\ResourceType|string $resource_type
Chris@18 74 * The JSON:API resource type or a JSON:API resource type name.
Chris@18 75 * @param string $id
Chris@18 76 * The resource ID.
Chris@18 77 * @param array $meta
Chris@18 78 * Any metadata for the ResourceIdentifier.
Chris@18 79 */
Chris@18 80 public function __construct($resource_type, $id, array $meta = []) {
Chris@18 81 assert(is_string($resource_type) || $resource_type instanceof ResourceType);
Chris@18 82 assert(!isset($meta[static::ARITY_KEY]) || is_int($meta[static::ARITY_KEY]) && $meta[static::ARITY_KEY] >= 0);
Chris@18 83 $this->resourceTypeName = is_string($resource_type) ? $resource_type : $resource_type->getTypeName();
Chris@18 84 $this->id = $id;
Chris@18 85 $this->meta = $meta;
Chris@18 86 if (!is_string($resource_type)) {
Chris@18 87 $this->resourceType = $resource_type;
Chris@18 88 }
Chris@18 89 }
Chris@18 90
Chris@18 91 /**
Chris@18 92 * Gets the ResourceIdentifier's JSON:API resource type name.
Chris@18 93 *
Chris@18 94 * @return string
Chris@18 95 * The JSON:API resource type name.
Chris@18 96 */
Chris@18 97 public function getTypeName() {
Chris@18 98 return $this->resourceTypeName;
Chris@18 99 }
Chris@18 100
Chris@18 101 /**
Chris@18 102 * {@inheritdoc}
Chris@18 103 */
Chris@18 104 public function getResourceType() {
Chris@18 105 if (!isset($this->resourceType)) {
Chris@18 106 /* @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
Chris@18 107 $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
Chris@18 108 $this->resourceType = $resource_type_repository->getByTypeName($this->getTypeName());
Chris@18 109 }
Chris@18 110 return $this->resourceType;
Chris@18 111 }
Chris@18 112
Chris@18 113 /**
Chris@18 114 * Gets the ResourceIdentifier's ID.
Chris@18 115 *
Chris@18 116 * @return string
Chris@18 117 * The ID.
Chris@18 118 */
Chris@18 119 public function getId() {
Chris@18 120 return $this->id;
Chris@18 121 }
Chris@18 122
Chris@18 123 /**
Chris@18 124 * Whether this ResourceIdentifier has an arity.
Chris@18 125 *
Chris@18 126 * @return int
Chris@18 127 * TRUE if the ResourceIdentifier has an arity, FALSE otherwise.
Chris@18 128 */
Chris@18 129 public function hasArity() {
Chris@18 130 return isset($this->meta[static::ARITY_KEY]);
Chris@18 131 }
Chris@18 132
Chris@18 133 /**
Chris@18 134 * Gets the ResourceIdentifier's arity.
Chris@18 135 *
Chris@18 136 * One must check self::hasArity() before calling this method.
Chris@18 137 *
Chris@18 138 * @return int
Chris@18 139 * The arity.
Chris@18 140 */
Chris@18 141 public function getArity() {
Chris@18 142 assert($this->hasArity());
Chris@18 143 return $this->meta[static::ARITY_KEY];
Chris@18 144 }
Chris@18 145
Chris@18 146 /**
Chris@18 147 * Returns a copy of the given ResourceIdentifier with the given arity.
Chris@18 148 *
Chris@18 149 * @param int $arity
Chris@18 150 * The new arity; must be a non-negative integer.
Chris@18 151 *
Chris@18 152 * @return static
Chris@18 153 * A newly created ResourceIdentifier with the given arity, otherwise
Chris@18 154 * the same.
Chris@18 155 */
Chris@18 156 public function withArity($arity) {
Chris@18 157 return new static($this->getResourceType(), $this->getId(), [static::ARITY_KEY => $arity] + $this->getMeta());
Chris@18 158 }
Chris@18 159
Chris@18 160 /**
Chris@18 161 * Gets the resource identifier objects metadata.
Chris@18 162 *
Chris@18 163 * @return array
Chris@18 164 * The metadata.
Chris@18 165 */
Chris@18 166 public function getMeta() {
Chris@18 167 return $this->meta;
Chris@18 168 }
Chris@18 169
Chris@18 170 /**
Chris@18 171 * Determines if two ResourceIdentifiers are the same.
Chris@18 172 *
Chris@18 173 * This method does not consider parallel relationships with different arity
Chris@18 174 * values to be duplicates. For that, use the isParallel() method.
Chris@18 175 *
Chris@18 176 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
Chris@18 177 * The first ResourceIdentifier object.
Chris@18 178 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
Chris@18 179 * The second ResourceIdentifier object.
Chris@18 180 *
Chris@18 181 * @return bool
Chris@18 182 * TRUE if both relationships reference the same resource and do not have
Chris@18 183 * two distinct arity's, FALSE otherwise.
Chris@18 184 *
Chris@18 185 * For example, if $a and $b both reference the same resource identifier,
Chris@18 186 * they can only be distinct if they *both* have an arity and those values
Chris@18 187 * are not the same. If $a or $b does not have an arity, they will be
Chris@18 188 * considered duplicates.
Chris@18 189 */
Chris@18 190 public static function isDuplicate(ResourceIdentifier $a, ResourceIdentifier $b) {
Chris@18 191 return static::compare($a, $b) === 0;
Chris@18 192 }
Chris@18 193
Chris@18 194 /**
Chris@18 195 * Determines if two ResourceIdentifiers identify the same resource object.
Chris@18 196 *
Chris@18 197 * This method does not consider arity.
Chris@18 198 *
Chris@18 199 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
Chris@18 200 * The first ResourceIdentifier object.
Chris@18 201 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
Chris@18 202 * The second ResourceIdentifier object.
Chris@18 203 *
Chris@18 204 * @return bool
Chris@18 205 * TRUE if both relationships reference the same resource, even when they
Chris@18 206 * have differing arity values, FALSE otherwise.
Chris@18 207 */
Chris@18 208 public static function isParallel(ResourceIdentifier $a, ResourceIdentifier $b) {
Chris@18 209 return static::compare($a->withArity(0), $b->withArity(0)) === 0;
Chris@18 210 }
Chris@18 211
Chris@18 212 /**
Chris@18 213 * Compares ResourceIdentifier objects.
Chris@18 214 *
Chris@18 215 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
Chris@18 216 * The first ResourceIdentifier object.
Chris@18 217 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
Chris@18 218 * The second ResourceIdentifier object.
Chris@18 219 *
Chris@18 220 * @return int
Chris@18 221 * Returns 0 if $a and $b are duplicate ResourceIdentifiers. If $a and $b
Chris@18 222 * identify the same resource but have distinct arity values, then the
Chris@18 223 * return value will be arity $a minus arity $b. -1 otherwise.
Chris@18 224 */
Chris@18 225 public static function compare(ResourceIdentifier $a, ResourceIdentifier $b) {
Chris@18 226 $result = strcmp(sprintf('%s:%s', $a->getTypeName(), $a->getId()), sprintf('%s:%s', $b->getTypeName(), $b->getId()));
Chris@18 227 // If type and ID do not match, return their ordering.
Chris@18 228 if ($result !== 0) {
Chris@18 229 return $result;
Chris@18 230 }
Chris@18 231 // If both $a and $b have an arity, then return the order by arity.
Chris@18 232 // Otherwise, they are considered equal.
Chris@18 233 return $a->hasArity() && $b->hasArity()
Chris@18 234 ? $a->getArity() - $b->getArity()
Chris@18 235 : 0;
Chris@18 236 }
Chris@18 237
Chris@18 238 /**
Chris@18 239 * Deduplicates an array of ResourceIdentifier objects.
Chris@18 240 *
Chris@18 241 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[] $resource_identifiers
Chris@18 242 * The list of ResourceIdentifiers to deduplicate.
Chris@18 243 *
Chris@18 244 * @return \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[]
Chris@18 245 * A deduplicated array of ResourceIdentifier objects.
Chris@18 246 *
Chris@18 247 * @see self::isDuplicate()
Chris@18 248 */
Chris@18 249 public static function deduplicate(array $resource_identifiers) {
Chris@18 250 return array_reduce(array_slice($resource_identifiers, 1), function ($deduplicated, $current) {
Chris@18 251 assert($current instanceof static);
Chris@18 252 return array_merge($deduplicated, array_reduce($deduplicated, function ($duplicate, $previous) use ($current) {
Chris@18 253 return $duplicate ?: static::isDuplicate($previous, $current);
Chris@18 254 }, FALSE) ? [] : [$current]);
Chris@18 255 }, array_slice($resource_identifiers, 0, 1));
Chris@18 256 }
Chris@18 257
Chris@18 258 /**
Chris@18 259 * Determines if an array of ResourceIdentifier objects is duplicate free.
Chris@18 260 *
Chris@18 261 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[] $resource_identifiers
Chris@18 262 * The list of ResourceIdentifiers to assess.
Chris@18 263 *
Chris@18 264 * @return bool
Chris@18 265 * Whether all the given resource identifiers are unique.
Chris@18 266 */
Chris@18 267 public static function areResourceIdentifiersUnique(array $resource_identifiers) {
Chris@18 268 return count($resource_identifiers) === count(static::deduplicate($resource_identifiers));
Chris@18 269 }
Chris@18 270
Chris@18 271 /**
Chris@18 272 * Creates a ResourceIdentifier object.
Chris@18 273 *
Chris@18 274 * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
Chris@18 275 * The entity reference field item from which to create the relationship.
Chris@18 276 * @param int $arity
Chris@18 277 * (optional) The arity of the relationship.
Chris@18 278 *
Chris@18 279 * @return self
Chris@18 280 * A new ResourceIdentifier object.
Chris@18 281 */
Chris@18 282 public static function toResourceIdentifier(EntityReferenceItem $item, $arity = NULL) {
Chris@18 283 $property_name = static::getDataReferencePropertyName($item);
Chris@18 284 $target = $item->get($property_name)->getValue();
Chris@18 285 if ($target === NULL) {
Chris@18 286 return static::getVirtualOrMissingResourceIdentifier($item);
Chris@18 287 }
Chris@18 288 assert($target instanceof EntityInterface);
Chris@18 289 /* @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
Chris@18 290 $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
Chris@18 291 $resource_type = $resource_type_repository->get($target->getEntityTypeId(), $target->bundle());
Chris@18 292 // Remove unwanted properties from the meta value, usually 'entity'
Chris@18 293 // and 'target_id'.
Chris@18 294 $properties = TypedDataInternalPropertiesHelper::getNonInternalProperties($item);
Chris@18 295 $meta = array_diff_key($properties, array_flip([$property_name, $item->getDataDefinition()->getMainPropertyName()]));
Chris@18 296 if (!is_null($arity)) {
Chris@18 297 $meta[static::ARITY_KEY] = $arity;
Chris@18 298 }
Chris@18 299 return new static($resource_type, $target->uuid(), $meta);
Chris@18 300 }
Chris@18 301
Chris@18 302 /**
Chris@18 303 * Creates an array of ResourceIdentifier objects.
Chris@18 304 *
Chris@18 305 * @param \Drupal\Core\Field\EntityReferenceFieldItemListInterface $items
Chris@18 306 * The entity reference field items from which to create the relationship
Chris@18 307 * array.
Chris@18 308 *
Chris@18 309 * @return self[]
Chris@18 310 * An array of new ResourceIdentifier objects with appropriate arity values.
Chris@18 311 */
Chris@18 312 public static function toResourceIdentifiers(EntityReferenceFieldItemListInterface $items) {
Chris@18 313 $relationships = [];
Chris@18 314 foreach ($items as $item) {
Chris@18 315 // Create a ResourceIdentifier from the field item. This will make it
Chris@18 316 // comparable with all previous field items. Here, it is assumed that the
Chris@18 317 // resource identifier is unique so it has no arity. If a parallel
Chris@18 318 // relationship is encountered, it will be assigned later.
Chris@18 319 $relationship = static::toResourceIdentifier($item);
Chris@18 320 // Now, iterate over the previously seen resource identifiers in reverse
Chris@18 321 // order. Reverse order is important so that when a parallel relationship
Chris@18 322 // is encountered, it will have the highest arity value so the current
Chris@18 323 // relationship's arity value can simply be incremented by one.
Chris@18 324 /* @var self $existing */
Chris@18 325 foreach (array_reverse($relationships, TRUE) as $index => $existing) {
Chris@18 326 $is_parallel = static::isParallel($existing, $relationship);
Chris@18 327 if ($is_parallel) {
Chris@18 328 // A parallel relationship has been found. If the previous
Chris@18 329 // relationship does not have an arity, it must now be assigned an
Chris@18 330 // arity of 0.
Chris@18 331 if (!$existing->hasArity()) {
Chris@18 332 $relationships[$index] = $existing->withArity(0);
Chris@18 333 }
Chris@18 334 // Since the new ResourceIdentifier is parallel, it must have an arity
Chris@18 335 // assigned to it that is the arity of the last parallel
Chris@18 336 // relationship's arity + 1.
Chris@18 337 $relationship = $relationship->withArity($relationships[$index]->getArity() + 1);
Chris@18 338 break;
Chris@18 339 }
Chris@18 340 }
Chris@18 341 // Finally, append the relationship to the list of ResourceIdentifiers.
Chris@18 342 $relationships[] = $relationship;
Chris@18 343 }
Chris@18 344 return $relationships;
Chris@18 345 }
Chris@18 346
Chris@18 347 /**
Chris@18 348 * Creates an array of ResourceIdentifier objects with arity on every value.
Chris@18 349 *
Chris@18 350 * @param \Drupal\Core\Field\EntityReferenceFieldItemListInterface $items
Chris@18 351 * The entity reference field items from which to create the relationship
Chris@18 352 * array.
Chris@18 353 *
Chris@18 354 * @return self[]
Chris@18 355 * An array of new ResourceIdentifier objects with appropriate arity values.
Chris@18 356 * Unlike self::toResourceIdentifiers(), this method does not omit arity
Chris@18 357 * when an identifier is not parallel to any other identifier.
Chris@18 358 */
Chris@18 359 public static function toResourceIdentifiersWithArityRequired(EntityReferenceFieldItemListInterface $items) {
Chris@18 360 return array_map(function (ResourceIdentifier $identifier) {
Chris@18 361 return $identifier->hasArity() ? $identifier : $identifier->withArity(0);
Chris@18 362 }, static::toResourceIdentifiers($items));
Chris@18 363 }
Chris@18 364
Chris@18 365 /**
Chris@18 366 * Creates a ResourceIdentifier object.
Chris@18 367 *
Chris@18 368 * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@18 369 * The entity from which to create the resource identifier.
Chris@18 370 *
Chris@18 371 * @return self
Chris@18 372 * A new ResourceIdentifier object.
Chris@18 373 */
Chris@18 374 public static function fromEntity(EntityInterface $entity) {
Chris@18 375 /* @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
Chris@18 376 $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
Chris@18 377 $resource_type = $resource_type_repository->get($entity->getEntityTypeId(), $entity->bundle());
Chris@18 378 return new static($resource_type, $entity->uuid());
Chris@18 379 }
Chris@18 380
Chris@18 381 /**
Chris@18 382 * Helper method to determine which field item property contains an entity.
Chris@18 383 *
Chris@18 384 * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
Chris@18 385 * The entity reference item for which to determine the entity property
Chris@18 386 * name.
Chris@18 387 *
Chris@18 388 * @return string
Chris@18 389 * The property name which has an entity as its value.
Chris@18 390 */
Chris@18 391 protected static function getDataReferencePropertyName(EntityReferenceItem $item) {
Chris@18 392 foreach ($item->getDataDefinition()->getPropertyDefinitions() as $property_name => $property_definition) {
Chris@18 393 if ($property_definition instanceof DataReferenceDefinitionInterface) {
Chris@18 394 return $property_name;
Chris@18 395 }
Chris@18 396 }
Chris@18 397 }
Chris@18 398
Chris@18 399 /**
Chris@18 400 * Creates a ResourceIdentifier for a NULL or FALSE entity reference item.
Chris@18 401 *
Chris@18 402 * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
Chris@18 403 * The entity reference field item.
Chris@18 404 *
Chris@18 405 * @return self
Chris@18 406 * A new ResourceIdentifier object.
Chris@18 407 */
Chris@18 408 protected static function getVirtualOrMissingResourceIdentifier(EntityReferenceItem $item) {
Chris@18 409 $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
Chris@18 410 $property_name = static::getDataReferencePropertyName($item);
Chris@18 411 $value = $item->get($property_name)->getValue();
Chris@18 412 assert($value === NULL);
Chris@18 413 $field = $item->getParent();
Chris@18 414 assert($field instanceof EntityReferenceFieldItemListInterface);
Chris@18 415 $host_entity = $field->getEntity();
Chris@18 416 assert($host_entity instanceof EntityInterface);
Chris@18 417 $resource_type = $resource_type_repository->get($host_entity->getEntityTypeId(), $host_entity->bundle());
Chris@18 418 assert($resource_type instanceof ResourceType);
Chris@18 419 $relatable_resource_types = $resource_type->getRelatableResourceTypesByField($field->getName());
Chris@18 420 $get_metadata = function ($type) {
Chris@18 421 return [
Chris@18 422 'links' => [
Chris@18 423 'help' => [
Chris@18 424 'href' => "https://www.drupal.org/docs/8/modules/json-api/core-concepts#$type",
Chris@18 425 'meta' => [
Chris@18 426 'about' => "Usage and meaning of the '$type' resource identifier.",
Chris@18 427 ],
Chris@18 428 ],
Chris@18 429 ],
Chris@18 430 ];
Chris@18 431 };
Chris@18 432 $resource_type = reset($relatable_resource_types);
Chris@18 433 // A non-empty entity reference field that refers to a non-existent entity
Chris@18 434 // is not a data integrity problem. For example, Term entities' "parent"
Chris@18 435 // entity reference field uses target_id zero to refer to the non-existent
Chris@18 436 // "<root>" term. And references to entities that no longer exist are not
Chris@18 437 // cleaned up by Drupal; hence we map it to a "missing" resource.
Chris@18 438 if ($field->getFieldDefinition()->getSetting('target_type') === 'taxonomy_term' && $item->get('target_id')->getCastedValue() === 0) {
Chris@18 439 if (count($relatable_resource_types) !== 1) {
Chris@18 440 throw new \RuntimeException('Relationships to virtual resources are possible only if a single resource type is relatable.');
Chris@18 441 }
Chris@18 442 return new static($resource_type, 'virtual', $get_metadata('virtual'));
Chris@18 443 }
Chris@18 444 else {
Chris@18 445 // In case of a dangling reference, it is impossible to determine which
Chris@18 446 // resource type it used to reference, because that requires knowing the
Chris@18 447 // referenced bundle, which Drupal does not store.
Chris@18 448 // If we can reliably determine the resource type of the dangling
Chris@18 449 // reference, use it; otherwise conjure a fake resource type out of thin
Chris@18 450 // air, one that indicates we don't know the bundle.
Chris@18 451 $resource_type = count($relatable_resource_types) > 1
Chris@18 452 ? new ResourceType('?', '?', '')
Chris@18 453 : reset($relatable_resource_types);
Chris@18 454 return new static($resource_type, 'missing', $get_metadata('missing'));
Chris@18 455 }
Chris@18 456 }
Chris@18 457
Chris@18 458 }