class CacheableNormalization

Same name in other branches
  1. 9 core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php \Drupal\jsonapi\Normalizer\Value\CacheableNormalization
  2. 10 core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php \Drupal\jsonapi\Normalizer\Value\CacheableNormalization
  3. 11.x core/modules/jsonapi/src/Normalizer/Value/CacheableNormalization.php \Drupal\jsonapi\Normalizer\Value\CacheableNormalization

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

Expanded class hierarchy of CacheableNormalization

See also

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

jsonapi.api.php

15 files declare their use of CacheableNormalization
DataNormalizer.php in core/modules/jsonapi/src/Normalizer/DataNormalizer.php
EntityReferenceFieldNormalizer.php in core/modules/jsonapi/src/Normalizer/EntityReferenceFieldNormalizer.php
FieldItemNormalizer.php in core/modules/jsonapi/src/Normalizer/FieldItemNormalizer.php
FieldNormalizer.php in core/modules/jsonapi/src/Normalizer/FieldNormalizer.php
JsonApiDocumentTopLevelNormalizer.php in core/modules/jsonapi/src/Normalizer/JsonApiDocumentTopLevelNormalizer.php

... See full list

File

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

Namespace

Drupal\jsonapi\Normalizer\Value
View source
class CacheableNormalization 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;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overrides
CacheableDependencyTrait::$cacheContexts protected property Cache contexts.
CacheableDependencyTrait::$cacheMaxAge protected property Cache max-age.
CacheableDependencyTrait::$cacheTags protected property Cache tags.
CacheableDependencyTrait::getCacheContexts public function 4
CacheableDependencyTrait::getCacheMaxAge public function 4
CacheableDependencyTrait::getCacheTags public function 4
CacheableDependencyTrait::setCacheability protected function Sets cacheability; useful for value object constructors.
CacheableNormalization::$normalization protected property A normalized value.
CacheableNormalization::aggregate public static function Collects an array of CacheableNormalizations into a single instance.
CacheableNormalization::getNormalization public function Gets the decorated normalization. 1
CacheableNormalization::hasNoNestedInstances protected static function Ensures that no nested values are instances of this class.
CacheableNormalization::omitIfEmpty public function Converts the object to a CacheableOmission if the normalization is empty.
CacheableNormalization::permanent public static function Creates a CacheableNormalization instance without any special cacheability. 1
CacheableNormalization::withCacheableDependency public function Gets a new CacheableNormalization with an additional dependency.
CacheableNormalization::__construct public function CacheableNormalization constructor. 1

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