class CacheableNormalization in Drupal 10

Use to store normalized data and its cacheability.

@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\Normalizer\Value\TemporaryArrayObjectThrowingExceptions extends \Drupal\jsonapi\Normalizer\Value\ArrayObject
  • class \Drupal\jsonapi\Normalizer\Value\CacheableNormalization implements CacheableDependencyInterface uses CacheableDependencyTrait

See also

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

jsonapi.api.php

6 files declare their use of CacheableNormalization

FieldItemNormalizerTest.php in core/modules/jsonapi/tests/src/Kernel/Normalizer/FieldItemNormalizerTest.php

LinkCollectionNormalizerTest.php in core/modules/jsonapi/tests/src/Kernel/Normalizer/LinkCollectionNormalizerTest.php

NodeTest.php in core/modules/jsonapi/tests/src/Functional/NodeTest.php

NormalizerBase.php in core/modules/jsonapi/src/Normalizer/NormalizerBase.php

ResourceObjectNormalizerCacherTest.php in core/modules/jsonapi/tests/src/Kernel/EventSubscriber/ResourceObjectNormalizerCacherTest.php

... See full list

File

core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php, line 19

Namespace

Drupal\jsonapi\Normalizer\Value

class CacheableNormalization extends TemporaryArrayObjectThrowingExceptions implements CacheableDependencyInterface {
  use CacheableDependencyTrait;

  /**
   * A normalized value.
   *
   * @var mixed
   */
  protected $normalization;

  /**
   * CacheableNormalization constructor.
   *
   * @param \Drupal\Core\Cache\CacheableDependencyInterface $cacheability
   *   The cacheability metadata for the normalized data.
   * @param array|string|int|float|bool|null $normalization
   *   The normalized data. This value must not contain any
   *   CacheableNormalizations.
   */
  public function __construct(CacheableDependencyInterface $cacheability, $normalization) {
    assert(is_array($normalization) && static::hasNoNestedInstances($normalization) || is_string($normalization) || is_int($normalization) || is_float($normalization) || is_bool($normalization) || is_null($normalization));
    $this->normalization = $normalization;
    $this
      ->setCacheability($cacheability);
  }

  /**
   * Creates a CacheableNormalization instance without any special cacheability.
   *
   * @param array|string|int|float|bool|null $normalization
   *   The normalized data. This value must not contain any
   *   CacheableNormalizations.
   *
   * @return static
   *   The CacheableNormalization.
   */
  public static function permanent($normalization) {
    return new static(new CacheableMetadata(), $normalization);
  }

  /**
   * Gets the decorated normalization.
   *
   * @return array|string|int|float|bool|null
   *   The normalization.
   */
  public function getNormalization() {
    return $this->normalization;
  }

  /**
   * Converts the object to a CacheableOmission if the normalization is empty.
   *
   * @return self|\Drupal\jsonapi\Normalizer\Value\CacheableOmission
   *   A CacheableOmission if the normalization is considered empty, self
   *   otherwise.
   */
  public function omitIfEmpty() {
    return empty($this->normalization) ? new CacheableOmission($this) : $this;
  }

  /**
   * Gets a new CacheableNormalization with an additional dependency.
   *
   * @param \Drupal\Core\Cache\CacheableDependencyInterface $dependency
   *   The new cacheable dependency.
   *
   * @return static
   *   A new object based on the current value with an additional cacheable
   *   dependency.
   */
  public function withCacheableDependency(CacheableDependencyInterface $dependency) {
    return new static(CacheableMetadata::createFromObject($this)
      ->addCacheableDependency($dependency), $this->normalization);
  }

  /**
   * Collects an array of CacheableNormalizations into a single instance.
   *
   * @param \Drupal\jsonapi\Normalizer\Value\CacheableNormalization[] $cacheable_normalizations
   *   An array of CacheableNormalizations.
   *
   * @return static
   *   A new CacheableNormalization. Each input value's cacheability will be
   *   merged into the return value's cacheability. The return value's
   *   normalization will be an array of the input's normalizations. This method
   *   does *not* behave like array_merge() or NestedArray::mergeDeep().
   */
  public static function aggregate(array $cacheable_normalizations) {
    assert(Inspector::assertAllObjects($cacheable_normalizations, CacheableNormalization::class));
    return new static(array_reduce($cacheable_normalizations, function (CacheableMetadata $merged, CacheableNormalization $item) {
      return $merged
        ->addCacheableDependency($item);
    }, new CacheableMetadata()), array_reduce(array_keys($cacheable_normalizations), function ($merged, $key) use ($cacheable_normalizations) {
      if (!$cacheable_normalizations[$key] instanceof CacheableOmission) {
        $merged[$key] = $cacheable_normalizations[$key]
          ->getNormalization();
      }
      return $merged;
    }, []));
  }

  /**
   * Ensures that no nested values are instances of this class.
   *
   * @param array|\Traversable $array
   *   The traversable object which may contain instance of this object.
   *
   * @return bool
   *   Whether the given object or its children have CacheableNormalizations in
   *   them.
   */
  protected static function hasNoNestedInstances($array) {
    foreach ($array as $value) {
      if ((is_array($value) || $value instanceof \Traversable) && !static::hasNoNestedInstances($value) || $value instanceof static) {
        return FALSE;
      }
    }
    return TRUE;
  }

}