CacheableNormalization.php

Same filename in other branches
  1. 9 core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php
  2. 8.9.x core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php
  3. 11.x core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php

Namespace

Drupal\jsonapi\Normalizer\Value

File

core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php

View source
<?php

namespace Drupal\jsonapi\Normalizer\Value;

use Drupal\Component\Assertion\Inspector;
use Drupal\Core\Cache\CacheableDependencyInterface;
use Drupal\Core\Cache\CacheableDependencyTrait;
use Drupal\Core\Cache\CacheableMetadata;

/**
 * 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.
 *
 * @see https://www.drupal.org/project/drupal/issues/3032787
 * @see jsonapi.api.php
 */
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_iterable($value) && !static::hasNoNestedInstances($value) || $value instanceof static) {
                return FALSE;
            }
        }
        return TRUE;
    }

}

Classes

Title Deprecated Summary
CacheableNormalization Use to store normalized data and its cacheability.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.