class ResourceIdentifier in Drupal 9

Same name and namespace in other branches

8 core/modules/jsonapi/src/JsonApiResource/ResourceIdentifier.php \Drupal\jsonapi\JsonApiResource\ResourceIdentifier

Represents a JSON:API resource identifier object.

The official JSON:API JSON-Schema document requires that no two resource identifier objects are duplicates, however Drupal allows multiple entity reference items to the same entity. Here, these are termed "parallel" relationships (as in "parallel edges" of a graph).

This class adds a concept of an

arity;

member under each its

meta;

object. The value of this member is an integer that is incremented by 1 (starting from 0) for each repeated resource identifier sharing a common

type;

and

id;

There are a number of helper methods to process the logic of dealing with resource identifies with and without arity.

@internal JSON:API maintains no PHP API. The API is the HTTP API. This class may change at any time and could break any dependencies on it.

Hierarchy

class \Drupal\jsonapi\JsonApiResource\ResourceIdentifier implements ResourceIdentifierInterface

Expanded class hierarchy of ResourceIdentifier

File

core/modules/jsonapi/src/JsonApiResource/ResourceIdentifier.php, line 38

Namespace

Drupal\jsonapi\JsonApiResource

View source

class ResourceIdentifier implements ResourceIdentifierInterface {
  const ARITY_KEY = 'arity';

  /**
   * The JSON:API resource type name.
   *
   * @var string
   */
  protected $resourceTypeName;

  /**
   * The JSON:API resource type.
   *
   * @var \Drupal\jsonapi\ResourceType\ResourceType
   */
  protected $resourceType;

  /**
   * The resource ID.
   *
   * @var string
   */
  protected $id;

  /**
   * The relationship's metadata.
   *
   * @var array
   */
  protected $meta;

  /**
   * ResourceIdentifier constructor.
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceType|string $resource_type
   *   The JSON:API resource type or a JSON:API resource type name.
   * @param string $id
   *   The resource ID.
   * @param array $meta
   *   Any metadata for the ResourceIdentifier.
   */
  public function __construct($resource_type, $id, array $meta = []) {
    assert(is_string($resource_type) || $resource_type instanceof ResourceType);
    assert(!isset($meta[static::ARITY_KEY]) || is_int($meta[static::ARITY_KEY]) && $meta[static::ARITY_KEY] >= 0);
    $this->resourceTypeName = is_string($resource_type) ? $resource_type : $resource_type
      ->getTypeName();
    $this->id = $id;
    $this->meta = $meta;
    if (!is_string($resource_type)) {
      $this->resourceType = $resource_type;
    }
  }

  /**
   * Gets the ResourceIdentifier's JSON:API resource type name.
   *
   * @return string
   *   The JSON:API resource type name.
   */
  public function getTypeName() {
    return $this->resourceTypeName;
  }

  /**
   * {@inheritdoc}
   */
  public function getResourceType() {
    if (!isset($this->resourceType)) {

      /** @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
      $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
      $this->resourceType = $resource_type_repository
        ->getByTypeName($this
        ->getTypeName());
    }
    return $this->resourceType;
  }

  /**
   * Gets the ResourceIdentifier's ID.
   *
   * @return string
   *   The ID.
   */
  public function getId() {
    return $this->id;
  }

  /**
   * Whether this ResourceIdentifier has an arity.
   *
   * @return int
   *   TRUE if the ResourceIdentifier has an arity, FALSE otherwise.
   */
  public function hasArity() {
    return isset($this->meta[static::ARITY_KEY]);
  }

  /**
   * Gets the ResourceIdentifier's arity.
   *
   * One must check self::hasArity() before calling this method.
   *
   * @return int
   *   The arity.
   */
  public function getArity() {
    assert($this
      ->hasArity());
    return $this->meta[static::ARITY_KEY];
  }

  /**
   * Returns a copy of the given ResourceIdentifier with the given arity.
   *
   * @param int $arity
   *   The new arity; must be a non-negative integer.
   *
   * @return static
   *   A newly created ResourceIdentifier with the given arity, otherwise
   *   the same.
   */
  public function withArity($arity) {
    return new static($this
      ->getResourceType(), $this
      ->getId(), [
      static::ARITY_KEY => $arity,
    ] + $this
      ->getMeta());
  }

  /**
   * Gets the resource identifier objects metadata.
   *
   * @return array
   *   The metadata.
   */
  public function getMeta() {
    return $this->meta;
  }

  /**
   * Determines if two ResourceIdentifiers are the same.
   *
   * This method does not consider parallel relationships with different arity
   * values to be duplicates. For that, use the isParallel() method.
   *
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
   *   The first ResourceIdentifier object.
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
   *   The second ResourceIdentifier object.
   *
   * @return bool
   *   TRUE if both relationships reference the same resource and do not have
   *   two distinct arity's, FALSE otherwise.
   *
   *   For example, if $a and $b both reference the same resource identifier,
   *   they can only be distinct if they *both* have an arity and those values
   *   are not the same. If $a or $b does not have an arity, they will be
   *   considered duplicates.
   */
  public static function isDuplicate(ResourceIdentifier $a, ResourceIdentifier $b) {
    return static::compare($a, $b) === 0;
  }

  /**
   * Determines if two ResourceIdentifiers identify the same resource object.
   *
   * This method does not consider arity.
   *
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
   *   The first ResourceIdentifier object.
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
   *   The second ResourceIdentifier object.
   *
   * @return bool
   *   TRUE if both relationships reference the same resource, even when they
   *   have differing arity values, FALSE otherwise.
   */
  public static function isParallel(ResourceIdentifier $a, ResourceIdentifier $b) {
    return static::compare($a
      ->withArity(0), $b
      ->withArity(0)) === 0;
  }

  /**
   * Compares ResourceIdentifier objects.
   *
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $a
   *   The first ResourceIdentifier object.
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $b
   *   The second ResourceIdentifier object.
   *
   * @return int
   *   Returns 0 if $a and $b are duplicate ResourceIdentifiers. If $a and $b
   *   identify the same resource but have distinct arity values, then the
   *   return value will be arity $a minus arity $b. -1 otherwise.
   */
  public static function compare(ResourceIdentifier $a, ResourceIdentifier $b) {
    $result = strcmp(sprintf('%s:%s', $a
      ->getTypeName(), $a
      ->getId()), sprintf('%s:%s', $b
      ->getTypeName(), $b
      ->getId()));

    // If type and ID do not match, return their ordering.
    if ($result !== 0) {
      return $result;
    }

    // If both $a and $b have an arity, then return the order by arity.
    // Otherwise, they are considered equal.
    return $a
      ->hasArity() && $b
      ->hasArity() ? $a
      ->getArity() - $b
      ->getArity() : 0;
  }

  /**
   * Deduplicates an array of ResourceIdentifier objects.
   *
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[] $resource_identifiers
   *   The list of ResourceIdentifiers to deduplicate.
   *
   * @return \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[]
   *   A deduplicated array of ResourceIdentifier objects.
   *
   * @see self::isDuplicate()
   */
  public static function deduplicate(array $resource_identifiers) {
    return array_reduce(array_slice($resource_identifiers, 1), function ($deduplicated, $current) {
      assert($current instanceof static);
      return array_merge($deduplicated, array_reduce($deduplicated, function ($duplicate, $previous) use ($current) {
        return $duplicate ?: static::isDuplicate($previous, $current);
      }, FALSE) ? [] : [
        $current,
      ]);
    }, array_slice($resource_identifiers, 0, 1));
  }

  /**
   * Determines if an array of ResourceIdentifier objects is duplicate free.
   *
   * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifier[] $resource_identifiers
   *   The list of ResourceIdentifiers to assess.
   *
   * @return bool
   *   Whether all the given resource identifiers are unique.
   */
  public static function areResourceIdentifiersUnique(array $resource_identifiers) {
    return count($resource_identifiers) === count(static::deduplicate($resource_identifiers));
  }

  /**
   * Creates a ResourceIdentifier object.
   *
   * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
   *   The entity reference field item from which to create the relationship.
   * @param int $arity
   *   (optional) The arity of the relationship.
   *
   * @return self
   *   A new ResourceIdentifier object.
   */
  public static function toResourceIdentifier(EntityReferenceItem $item, $arity = NULL) {
    $property_name = static::getDataReferencePropertyName($item);
    $target = $item
      ->get($property_name)
      ->getValue();
    if ($target === NULL) {
      return static::getVirtualOrMissingResourceIdentifier($item);
    }
    assert($target instanceof EntityInterface);

    /** @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
    $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
    $resource_type = $resource_type_repository
      ->get($target
      ->getEntityTypeId(), $target
      ->bundle());

    // Remove unwanted properties from the meta value, usually 'entity'
    // and 'target_id'.
    $properties = TypedDataInternalPropertiesHelper::getNonInternalProperties($item);
    $main_property_name = $item
      ->getDataDefinition()
      ->getMainPropertyName();
    $meta = array_diff_key($properties, array_flip([
      $property_name,
      $main_property_name,
    ]));
    if (!is_null($arity)) {
      $meta[static::ARITY_KEY] = $arity;
    }
    $meta["drupal_internal__{$main_property_name}"] = $properties[$main_property_name];
    return new static($resource_type, $target
      ->uuid(), $meta);
  }

  /**
   * Creates an array of ResourceIdentifier objects.
   *
   * @param \Drupal\Core\Field\EntityReferenceFieldItemListInterface $items
   *   The entity reference field items from which to create the relationship
   *   array.
   *
   * @return self[]
   *   An array of new ResourceIdentifier objects with appropriate arity values.
   */
  public static function toResourceIdentifiers(EntityReferenceFieldItemListInterface $items) {
    $relationships = [];
    foreach ($items
      ->filterEmptyItems() as $item) {

      // Create a ResourceIdentifier from the field item. This will make it
      // comparable with all previous field items. Here, it is assumed that the
      // resource identifier is unique so it has no arity. If a parallel
      // relationship is encountered, it will be assigned later.
      $relationship = static::toResourceIdentifier($item);
      if ($relationship
        ->getResourceType()
        ->isInternal()) {
        continue;
      }

      // Now, iterate over the previously seen resource identifiers in reverse
      // order. Reverse order is important so that when a parallel relationship
      // is encountered, it will have the highest arity value so the current
      // relationship's arity value can simply be incremented by one.

      /** @var \Drupal\jsonapi\JsonApiResource\ResourceIdentifier $existing */
      foreach (array_reverse($relationships, TRUE) as $index => $existing) {
        $is_parallel = static::isParallel($existing, $relationship);
        if ($is_parallel) {

          // A parallel relationship has been found. If the previous
          // relationship does not have an arity, it must now be assigned an
          // arity of 0.
          if (!$existing
            ->hasArity()) {
            $relationships[$index] = $existing
              ->withArity(0);
          }

          // Since the new ResourceIdentifier is parallel, it must have an arity
          // assigned to it that is the arity of the last parallel
          // relationship's arity + 1.
          $relationship = $relationship
            ->withArity($relationships[$index]
            ->getArity() + 1);
          break;
        }
      }

      // Finally, append the relationship to the list of ResourceIdentifiers.
      $relationships[] = $relationship;
    }
    return $relationships;
  }

  /**
   * Creates an array of ResourceIdentifier objects with arity on every value.
   *
   * @param \Drupal\Core\Field\EntityReferenceFieldItemListInterface $items
   *   The entity reference field items from which to create the relationship
   *   array.
   *
   * @return self[]
   *   An array of new ResourceIdentifier objects with appropriate arity values.
   *   Unlike self::toResourceIdentifiers(), this method does not omit arity
   *   when an identifier is not parallel to any other identifier.
   */
  public static function toResourceIdentifiersWithArityRequired(EntityReferenceFieldItemListInterface $items) {
    return array_map(function (ResourceIdentifier $identifier) {
      return $identifier
        ->hasArity() ? $identifier : $identifier
        ->withArity(0);
    }, static::toResourceIdentifiers($items));
  }

  /**
   * Creates a ResourceIdentifier object.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   The entity from which to create the resource identifier.
   *
   * @return self
   *   A new ResourceIdentifier object.
   */
  public static function fromEntity(EntityInterface $entity) {

    /** @var \Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface $resource_type_repository */
    $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
    $resource_type = $resource_type_repository
      ->get($entity
      ->getEntityTypeId(), $entity
      ->bundle());
    return new static($resource_type, $entity
      ->uuid());
  }

  /**
   * Helper method to determine which field item property contains an entity.
   *
   * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
   *   The entity reference item for which to determine the entity property
   *   name.
   *
   * @return string
   *   The property name which has an entity as its value.
   */
  protected static function getDataReferencePropertyName(EntityReferenceItem $item) {
    foreach ($item
      ->getDataDefinition()
      ->getPropertyDefinitions() as $property_name => $property_definition) {
      if ($property_definition instanceof DataReferenceDefinitionInterface) {
        return $property_name;
      }
    }
  }

  /**
   * Creates a ResourceIdentifier for a NULL or FALSE entity reference item.
   *
   * @param \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem $item
   *   The entity reference field item.
   *
   * @return self
   *   A new ResourceIdentifier object.
   */
  protected static function getVirtualOrMissingResourceIdentifier(EntityReferenceItem $item) {
    $resource_type_repository = \Drupal::service('jsonapi.resource_type.repository');
    $property_name = static::getDataReferencePropertyName($item);
    $value = $item
      ->get($property_name)
      ->getValue();
    assert($value === NULL);
    $field = $item
      ->getParent();
    assert($field instanceof EntityReferenceFieldItemListInterface);
    $host_entity = $field
      ->getEntity();
    assert($host_entity instanceof EntityInterface);
    $resource_type = $resource_type_repository
      ->get($host_entity
      ->getEntityTypeId(), $host_entity
      ->bundle());
    assert($resource_type instanceof ResourceType);
    $relatable_resource_types = $resource_type
      ->getRelatableResourceTypesByField($resource_type
      ->getPublicName($field
      ->getName()));
    assert(!empty($relatable_resource_types));
    $get_metadata = function ($type) {
      return [
        'links' => [
          'help' => [
            'href' => "https://www.drupal.org/docs/8/modules/json-api/core-concepts#{$type}",
            'meta' => [
              'about' => "Usage and meaning of the '{$type}' resource identifier.",
            ],
          ],
        ],
      ];
    };
    $resource_type = reset($relatable_resource_types);

    // A non-empty entity reference field that refers to a non-existent entity
    // is not a data integrity problem. For example, Term entities' "parent"
    // entity reference field uses target_id zero to refer to the non-existent
    // "<root>" term. And references to entities that no longer exist are not
    // cleaned up by Drupal; hence we map it to a "missing" resource.
    if ($field
      ->getFieldDefinition()
      ->getSetting('target_type') === 'taxonomy_term' && $item
      ->get('target_id')
      ->getCastedValue() === 0) {
      if (count($relatable_resource_types) !== 1) {
        throw new \RuntimeException('Relationships to virtual resources are possible only if a single resource type is relatable.');
      }
      return new static($resource_type, 'virtual', $get_metadata('virtual'));
    }
    else {

      // In case of a dangling reference, it is impossible to determine which
      // resource type it used to reference, because that requires knowing the
      // referenced bundle, which Drupal does not store.
      // If we can reliably determine the resource type of the dangling
      // reference, use it; otherwise conjure a fake resource type out of thin
      // air, one that indicates we don't know the bundle.
      $resource_type = count($relatable_resource_types) > 1 ? new ResourceType('?', '?', '') : reset($relatable_resource_types);
      return new static($resource_type, 'missing', $get_metadata('missing'));
    }
  }

}

Members

Name	Modifiers	Type	Description
ResourceIdentifier::$id	protected	property	The resource ID.
ResourceIdentifier::$meta	protected	property	The relationship's metadata.
ResourceIdentifier::$resourceType	protected	property	The JSON:API resource type.
ResourceIdentifier::$resourceTypeName	protected	property	The JSON:API resource type name.
ResourceIdentifier::areResourceIdentifiersUnique	public static	function	Determines if an array of ResourceIdentifier objects is duplicate free.
ResourceIdentifier::ARITY_KEY		constant
ResourceIdentifier::compare	public static	function	Compares ResourceIdentifier objects.
ResourceIdentifier::deduplicate	public static	function	Deduplicates an array of ResourceIdentifier objects.
ResourceIdentifier::fromEntity	public static	function	Creates a ResourceIdentifier object.
ResourceIdentifier::getArity	public	function	Gets the ResourceIdentifier's arity.
ResourceIdentifier::getDataReferencePropertyName	protected static	function	Helper method to determine which field item property contains an entity.
ResourceIdentifier::getId	public	function	Gets the ResourceIdentifier's ID. Overrides ResourceIdentifierInterface::getId
ResourceIdentifier::getMeta	public	function	Gets the resource identifier objects metadata.
ResourceIdentifier::getResourceType	public	function	Gets the resource identifier's JSON:API resource type. Overrides ResourceIdentifierInterface::getResourceType
ResourceIdentifier::getTypeName	public	function	Gets the ResourceIdentifier's JSON:API resource type name. Overrides ResourceIdentifierInterface::getTypeName
ResourceIdentifier::getVirtualOrMissingResourceIdentifier	protected static	function	Creates a ResourceIdentifier for a NULL or FALSE entity reference item.
ResourceIdentifier::hasArity	public	function	Whether this ResourceIdentifier has an arity.
ResourceIdentifier::isDuplicate	public static	function	Determines if two ResourceIdentifiers are the same.
ResourceIdentifier::isParallel	public static	function	Determines if two ResourceIdentifiers identify the same resource object.
ResourceIdentifier::toResourceIdentifier	public static	function	Creates a ResourceIdentifier object.
ResourceIdentifier::toResourceIdentifiers	public static	function	Creates an array of ResourceIdentifier objects.
ResourceIdentifier::toResourceIdentifiersWithArityRequired	public static	function	Creates an array of ResourceIdentifier objects with arity on every value.
ResourceIdentifier::withArity	public	function	Returns a copy of the given ResourceIdentifier with the given arity.
ResourceIdentifier::__construct	public	function	ResourceIdentifier constructor.

You are here

class ResourceIdentifier in Drupal 9

Hierarchy

See also

File

Namespace

Members

API Navigation