class LinkCollectionNormalizer in JSON:API 8.2

Normalizes a LinkCollection object.

The JSON:API specification has the concept of a "links collection". A links collection is a JSON object where each member of the object is a "link object". Unfortunately, this means that it is not possible to have more than one link for a given key.

When normalizing more than one link in a LinkCollection with the same key, a unique and random string is appended to the link's key after a colon (:) to differentiate the links.

This may change with a later version of the JSON:API specification.

@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\serialization\Normalizer\NormalizerBase implements \Symfony\Component\Serializer\SerializerAwareInterface, CacheableNormalizerInterface uses \Symfony\Component\Serializer\SerializerAwareTrait
  • class \Drupal\jsonapi\Normalizer\NormalizerBase
    • class \Drupal\jsonapi\Normalizer\LinkCollectionNormalizer

See also

https://www.drupal.org/project/jsonapi/issues/3032787

jsonapi.api.php

1 string reference to 'LinkCollectionNormalizer'

jsonapi.services.yml in ./jsonapi.services.yml

jsonapi.services.yml

1 service uses LinkCollectionNormalizer

serializer.normalizer.link_collection.jsonapi in ./jsonapi.services.yml

Drupal\jsonapi\Normalizer\LinkCollectionNormalizer

File

src/Normalizer/LinkCollectionNormalizer.php, line 30

Namespace

Drupal\jsonapi\Normalizer

class LinkCollectionNormalizer extends NormalizerBase {

  /**
   * The normalizer $context key name for the key of an individual link.
   *
   * @var string
   */
  const LINK_KEY = 'jsonapi_links_object_link_key';

  /**
   * The normalizer $context key name for the context object of the link.
   *
   * @var string
   */
  const LINK_CONTEXT = 'jsonapi_links_object_context';

  /**
   * {@inheritdoc}
   */
  protected $supportedInterfaceOrClass = LinkCollection::class;

  /**
   * A random string to use when hashing links.
   *
   * This string is unique per instance of a link collection, but always the
   * same within it. This means that link key hashes will be non-deterministic
   * for outside observers, but two links within the same collection will always
   * have the same hash value.
   *
   * This is not used for cryptographic purposes.
   *
   * @var string
   */
  protected $hashSalt;

  /**
   * {@inheritdoc}
   */
  public function normalize($object, $format = NULL, array $context = []) {
    assert($object instanceof LinkCollection);
    $normalized = [];

    /* @var \Drupal\jsonapi\JsonApiResource\Link $link */
    foreach ($object as $key => $links) {
      $is_multiple = count($links) > 1;
      foreach ($links as $link) {
        $link_key = $is_multiple ? sprintf('%s:%s', $key, $this
          ->hashByHref($link)) : $key;
        $attributes = $link
          ->getTargetAttributes();
        $normalization = array_merge([
          'href' => $link
            ->getHref(),
        ], !empty($attributes) ? [
          'meta' => $attributes,
        ] : []);
        $normalized[$link_key] = new CacheableNormalization($link, $normalization);
      }
    }
    return CacheableNormalization::aggregate($normalized);
  }

  /**
   * Hashes a link by its href.
   *
   * @param \Drupal\jsonapi\JsonApiResource\Link $link
   *   A link to be hashed.
   *
   * @return string
   *   A 7 character alphanumeric hash.
   */
  protected function hashByHref(Link $link) {
    if (!$this->hashSalt) {
      $this->hashSalt = Crypt::randomBytesBase64();
    }
    return substr(str_replace([
      '-',
      '_',
    ], '', Crypt::hashBase64($this->hashSalt . $link
      ->getHref())), 0, 7);
  }

}

Members

Name	Modifiers	Type	Description	Overrides
CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY		constant	Name of key for bubbling cacheability metadata via serialization context.
LinkCollectionNormalizer::$hashSalt	protected	property	A random string to use when hashing links.
LinkCollectionNormalizer::$supportedInterfaceOrClass	protected	property	The interface or class that this Normalizer supports. Overrides NormalizerBase::$supportedInterfaceOrClass
LinkCollectionNormalizer::hashByHref	protected	function	Hashes a link by its href.
LinkCollectionNormalizer::LINK_CONTEXT		constant	The normalizer $context key name for the context object of the link.
LinkCollectionNormalizer::LINK_KEY		constant	The normalizer $context key name for the key of an individual link.
LinkCollectionNormalizer::normalize	public	function	Normalizes an object into a set of arrays/scalars.
NormalizerBase::$format	protected	property	List of formats which supports (de-)normalization. Overrides NormalizerBase::$format
NormalizerBase::addCacheableDependency	protected	function	Adds cacheability if applicable.
NormalizerBase::checkFormat	protected	function	Checks if the provided format is supported by this normalizer. Overrides NormalizerBase::checkFormat
NormalizerBase::rasterizeValueRecursive	protected static	function	Rasterizes a value recursively.
NormalizerBase::supportsDenormalization	public	function	Implements \Symfony\Component\Serializer\Normalizer\DenormalizerInterface::supportsDenormalization()	1
NormalizerBase::supportsNormalization	public	function	Checks whether the given class is supported for normalization by this normalizer.	1