ResourceObjectNormalizer.php

<?php

namespace Drupal\jsonapi\Normalizer;

use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Entity\EntityFieldManagerInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Entity\FieldableEntityInterface;
use Drupal\Core\Field\EntityReferenceFieldItemListInterface;
use Drupal\Core\Field\FieldItemListInterface;
use Drupal\jsonapi\Events\CollectRelationshipMetaEvent;
use Drupal\jsonapi\Events\CollectResourceObjectMetaEvent;
use Drupal\jsonapi\EventSubscriber\ResourceObjectNormalizationCacher;
use Drupal\jsonapi\JsonApiResource\Relationship;
use Drupal\jsonapi\JsonApiResource\ResourceObject;
use Drupal\jsonapi\JsonApiSpec;
use Drupal\jsonapi\Normalizer\Value\CacheableNormalization;
use Drupal\jsonapi\Normalizer\Value\CacheableOmission;
use Drupal\jsonapi\ResourceType\ResourceType;
use Drupal\jsonapi\ResourceType\ResourceTypeField;
use Drupal\jsonapi\Serializer\Serializer;
use Drupal\serialization\Normalizer\SchematicNormalizerTrait;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;

/**
 * Converts the JSON:API module ResourceObject into a JSON:API array structure.
 *
 * @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 ResourceObjectNormalizer extends NormalizerBase {
    use SchematicNormalizerTrait;
    
    /**
     * The entity normalization cacher.
     *
     * @var \Drupal\jsonapi\EventSubscriber\ResourceObjectNormalizationCacher
     */
    protected $cacher;
    
    /**
     * @var mixed|\Symfony\Component\EventDispatcher\EventDispatcherInterface|null
     */
    private EventDispatcherInterface $eventDispatcher;
    
    /**
     * @var mixed|\Drupal\Core\Entity\EntityFieldManagerInterface|null
     */
    private EntityFieldManagerInterface $entityFieldManager;
    
    /**
     * @var mixed|\Drupal\Core\Entity\EntityTypeManagerInterface|null
     */
    private EntityTypeManagerInterface $entityTypeManager;
    
    /**
     * Constructs a ResourceObjectNormalizer object.
     *
     * @param \Drupal\jsonapi\EventSubscriber\ResourceObjectNormalizationCacher $cacher
     *   The entity normalization cacher.
     * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $event_dispatcher
     *   The event dispatcher.
     * @param \Drupal\Core\Entity\EntityFieldManagerInterface $entity_field_manager
     *   The entity field manager.
     * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
     *   The entity type manager.
     */
    public function __construct(ResourceObjectNormalizationCacher $cacher, ?EventDispatcherInterface $event_dispatcher = NULL, ?EntityFieldManagerInterface $entity_field_manager = NULL, ?EntityTypeManagerInterface $entity_type_manager = NULL) {
        $this->cacher = $cacher;
        if ($event_dispatcher === NULL) {
            @trigger_error('Calling ' . __METHOD__ . '() without the $event_dispatcher argument is deprecated in drupal:11.2.0 and will be required in drupal:12.0.0. See https://www.drupal.org/node/3280569', E_USER_DEPRECATED);
            $event_dispatcher = \Drupal::service('event_dispatcher');
        }
        $this->eventDispatcher = $event_dispatcher;
        if ($entity_field_manager === NULL) {
            @trigger_error('Calling ' . __METHOD__ . '() without the $entity_field_manager argument is deprecated in drupal:11.2.0 and will be required in drupal:12.0.0. See https://www.drupal.org/node/3031367', E_USER_DEPRECATED);
            $entity_field_manager = \Drupal::service('entity_field_manager');
        }
        $this->entityFieldManager = $entity_field_manager;
        if ($entity_type_manager === NULL) {
            @trigger_error('Calling ' . __METHOD__ . '() without the $entity_type_manager argument is deprecated in drupal:11.2.0 and will be required in drupal:12.0.0. See https://www.drupal.org/node/3031367', E_USER_DEPRECATED);
            $entity_type_manager = \Drupal::service('entity_type_manager');
        }
        $this->entityTypeManager = $entity_type_manager;
    }
    
    /**
     * {@inheritdoc}
     */
    public function supportsDenormalization($data, string $type, ?string $format = NULL, array $context = []) : bool {
        return FALSE;
    }
    
    /**
     * {@inheritdoc}
     */
    public function doNormalize($object, $format = NULL, array $context = []) : array|string|int|float|bool|\ArrayObject|null {
        assert($object instanceof ResourceObject);
        // If the fields to use were specified, only output those field values.
        $context['resource_object'] = $object;
        $resource_type = $object->getResourceType();
        $resource_type_name = $resource_type->getTypeName();
        $fields = $object->getFields();
        // Get the bundle ID of the requested resource. This is used to determine if
        // this is a bundle level resource or an entity level resource.
        if (!empty($context['sparse_fieldset'][$resource_type_name])) {
            $field_names = $context['sparse_fieldset'][$resource_type_name];
        }
        else {
            $field_names = array_keys($fields);
        }
        $normalization_parts = $this->getNormalization($field_names, $object, $format, $context);
        // Keep only the requested fields (the cached normalization gradually grows
        // to the complete set of fields).
        $fields = $normalization_parts[ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_FIELDS];
        $field_normalizations = array_intersect_key($fields, array_flip($field_names));
        $relationship_field_names = array_keys($resource_type->getRelatableResourceTypes());
        $attributes = array_diff_key($field_normalizations, array_flip($relationship_field_names));
        $relationships = array_intersect_key($field_normalizations, array_flip($relationship_field_names));
        $event = new CollectResourceObjectMetaEvent($object, $context);
        $this->eventDispatcher
            ->dispatch($event);
        $entity_normalization = array_filter($normalization_parts[ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_BASE] + [
            'attributes' => CacheableNormalization::aggregate($attributes)->omitIfEmpty(),
            'relationships' => CacheableNormalization::aggregate($relationships)->omitIfEmpty(),
            'meta' => count($event->getMeta()) > 0 ? new CacheableNormalization($event, $event->getMeta()) : '',
        ]);
        return CacheableNormalization::aggregate($entity_normalization)->withCacheableDependency($object);
    }
    
    /**
     * Normalizes an entity using the given fieldset.
     *
     * @param string[] $field_names
     *   The field names to normalize (the sparse fieldset, if any).
     * @param \Drupal\jsonapi\JsonApiResource\ResourceObject $object
     *   The resource object to partially normalize.
     * @param string $format
     *   The format in which the normalization will be encoded.
     * @param array $context
     *   Context options for the normalizer.
     *
     * @return array
     *   An array with two key-value pairs:
     *   - 'base': array, the base normalization of the entity, that does not
     *             depend on which sparse fieldset was requested.
     *   - 'fields': CacheableNormalization for all requested fields.
     *
     * @see ::normalize()
     */
    protected function getNormalization(array $field_names, ResourceObject $object, $format = NULL, array $context = []) {
        $cached_normalization_parts = $this->cacher
            ->get($object);
        $normalizer_values = $cached_normalization_parts !== FALSE ? $cached_normalization_parts : static::buildEmptyNormalization($object);
        $fields =& $normalizer_values[ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_FIELDS];
        $non_cached_fields = array_diff_key($object->getFields(), $fields);
        $non_cached_requested_fields = array_intersect_key($non_cached_fields, array_flip($field_names));
        foreach ($non_cached_requested_fields as $field_name => $field) {
            $fields[$field_name] = $this->serializeField($field, $context, $format);
        }
        // Add links if missing.
        $base =& $normalizer_values[ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_BASE];
        $base['links'] = $base['links'] ?? $this->serializer
            ->normalize($object->getLinks(), $format, $context)
            ->omitIfEmpty();
        if (!empty($non_cached_requested_fields)) {
            $this->cacher
                ->saveOnTerminate($object, $normalizer_values);
        }
        return $normalizer_values;
    }
    
    /**
     * Builds the empty normalization structure for cache misses.
     *
     * @param \Drupal\jsonapi\JsonApiResource\ResourceObject $object
     *   The resource object being normalized.
     *
     * @return array
     *   The normalization structure as defined in ::getNormalization().
     *
     * @see ::getNormalization()
     */
    protected static function buildEmptyNormalization(ResourceObject $object) {
        return [
            ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_BASE => [
                'type' => CacheableNormalization::permanent($object->getResourceType()
                    ->getTypeName()),
                'id' => CacheableNormalization::permanent($object->getId()),
            ],
            ResourceObjectNormalizationCacher::RESOURCE_CACHE_SUBSET_FIELDS => [],
        ];
    }
    
    /**
     * Serializes a given field.
     *
     * @param mixed $field
     *   The field to serialize.
     * @param array $context
     *   The normalization context.
     * @param string $format
     *   The serialization format.
     *
     * @return \Drupal\jsonapi\Normalizer\Value\CacheableNormalization
     *   The normalized value.
     */
    protected function serializeField($field, array $context, $format) {
        // Only content entities contain FieldItemListInterface fields. Since config
        // entities do not have "real" fields and therefore do not have field access
        // restrictions.
        if ($field instanceof FieldItemListInterface) {
            $field_access_result = $field->access('view', $context['account'] ?? NULL, TRUE);
            if (!$field_access_result->isAllowed()) {
                return new CacheableOmission(CacheableMetadata::createFromObject($field_access_result));
            }
            if ($field instanceof EntityReferenceFieldItemListInterface) {
                // Build the relationship object based on the entity reference and
                // normalize that object instead.
                assert(!empty($context['resource_object']) && $context['resource_object'] instanceof ResourceObject);
                $resource_object = $context['resource_object'];
                $resource_field_name = $resource_object->getResourceType()
                    ->getFieldByInternalName($field->getName())
                    ->getPublicName();
                $collect_meta_event = new CollectRelationshipMetaEvent($resource_object, $resource_field_name);
                $this->eventDispatcher
                    ->dispatch($collect_meta_event);
                $relationship = Relationship::createFromEntityReferenceField(context: $resource_object, field: $field, meta: $collect_meta_event->getMeta());
                $normalized_field = $this->serializer
                    ->normalize($relationship, $format, $context);
                $normalized_field = $normalized_field->withCacheableDependency($collect_meta_event);
            }
            else {
                $normalized_field = $this->serializer
                    ->normalize($field, $format, $context);
            }
            assert($normalized_field instanceof CacheableNormalization);
            return $normalized_field->withCacheableDependency(CacheableMetadata::createFromObject($field_access_result));
        }
        else {
            // @todo Replace this workaround after https://www.drupal.org/node/3043245
            //   or remove the need for this in https://www.drupal.org/node/2942975.
            //   See \Drupal\layout_builder\Normalizer\LayoutEntityDisplayNormalizer.
            if (is_a($context['resource_object']->getResourceType()
                ->getDeserializationTargetClass(), 'Drupal\\layout_builder\\Entity\\LayoutBuilderEntityViewDisplay', TRUE) && $context['resource_object']->getField('third_party_settings') === $field) {
                unset($field['layout_builder']['sections']);
            }
            // Config "fields" in this case are arrays or primitives and do not need
            // to be normalized.
            return CacheableNormalization::permanent($field);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function getNormalizationSchema(mixed $object, array $context = []) : array {
        if (is_string($object)) {
            // Without a true object we can only provide a generic schema.
            return [
                '$ref' => JsonApiSpec::SUPPORTED_SPECIFICATION_JSON_SCHEMA . '#/definitions/resource',
            ];
        }
        // ResourceObject is usually instantiated from a specific entity, however
        // a placeholder can be created for purposes of schema generation which
        // would provide access to the resource type, but not contain any "live"
        // data.
        assert($object instanceof ResourceObject);
        $attributes_schema = [];
        $relationships_schema = [];
        $this->entityTypeManager
            ->getDefinition($object->getResourceType()
            ->getEntityTypeId())
            ->entityClassImplements(FieldableEntityInterface::class) ? $this->processContentEntitySchema($object, $context, $attributes_schema, $relationships_schema) : $this->processConfigEntitySchema($object->getResourceType(), $context, $attributes_schema);
        return [
            'allOf' => [
                [
                    '$ref' => JsonApiSpec::SUPPORTED_SPECIFICATION_JSON_SCHEMA . '#/definitions/resourceIdentification',
                ],
            ],
            'properties' => [
                'meta' => [
                    '$ref' => JsonApiSpec::SUPPORTED_SPECIFICATION_JSON_SCHEMA . '#/definitions/meta',
                ],
                'links' => [
                    '$ref' => JsonApiSpec::SUPPORTED_SPECIFICATION_JSON_SCHEMA . '#/definitions/resourceLinks',
                ],
                // If the array is empty we must return an object so it won't encode as
                // an array; we don't cast the value here so the returned value is still
                // traversable as an array when accessed in PHP.
'attributes' => $attributes_schema ?: new \ArrayObject(),
                'relationships' => $relationships_schema ?: new \ArrayObject(),
            ],
            'unevaluatedProperties' => FALSE,
        ];
    }
    protected function processConfigEntitySchema(ResourceType $resource_type, array $context, array &$attributes_schema) : void {
        // This is largely the same as in ResourceObject but without a real entity.
        $fields = $resource_type->getFields();
        // Filter the array based on the field names.
        $enabled_field_names = array_filter(array_keys($fields), static fn(string $internal_field_name) => $resource_type->isFieldEnabled($internal_field_name));
        // Return a sub-array of $output containing the keys in $enabled_fields.
        $input = array_intersect_key($fields, array_flip($enabled_field_names));
        foreach ($input as $field_name => $field_value) {
            $attributes_schema['properties'][$resource_type->getPublicName($field_name)] = [
                'title' => $field_name,
            ];
        }
    }
    protected function processContentEntitySchema(ResourceObject $resource_object, array $context, array &$attributes_schema, &$relationships_schema) : void {
        // Actual normalization supports sparse fieldsets, however we provide schema
        // for all possible fields that may be retrieved.
        $resource_type = $resource_object->getResourceType();
        $field_definitions = $this->entityFieldManager
            ->getFieldDefinitions($resource_type->getEntityTypeId(), $resource_type->getBundle());
        $resource_fields = $resource_type->getFields();
        // User resource objects contain a read-only attribute that is not a real
        // field on the user entity type.
        // @see \Drupal\jsonapi\JsonApiResource\ResourceObject::extractContentEntityFields()
        // @todo Eliminate this special casing in https://www.drupal.org/project/drupal/issues/3079254.
        if ($resource_type->getEntityTypeId() === 'user') {
            $resource_fields = array_diff_key($resource_fields, array_flip([
                $resource_type->getPublicName('display_name'),
            ]));
        }
        
        /** @var \Drupal\Core\Field\FieldDefinitionInterface[] $fields */
        $fields = array_reduce($resource_fields, function (array $carry, ResourceTypeField $resource_field) use ($field_definitions) {
            if (!$resource_field->isFieldEnabled()) {
                return $carry;
            }
            $carry[$resource_field->getPublicName()] = $field_definitions[$resource_field->getInternalName()];
            return $carry;
        }, []);
        assert($this->serializer instanceof Serializer);
        $relationship_field_names = array_keys($resource_type->getRelatableResourceTypes());
        $create_values = [];
        if ($bundle_key = $this->entityTypeManager
            ->getDefinition($resource_type->getEntityTypeId())
            ->getKey('bundle')) {
            $create_values = [
                $bundle_key => $resource_type->getBundle(),
            ];
        }
        $stub_entity = $this->entityTypeManager
            ->getStorage($resource_type->getEntityTypeId())
            ->create($create_values);
        foreach ($fields as $field_name => $field) {
            $stub_field = $stub_entity->get($field->getName());
            if ($stub_field instanceof EntityReferenceFieldItemListInterface) {
                // Build the relationship object based on the entity reference and
                // retrieve normalizer for that object instead.
                // @see ::serializeField()
                $relationship = Relationship::createFromEntityReferenceField($resource_object, $stub_field);
                $schema = $this->serializer
                    ->getJsonSchema($relationship, $context);
            }
            else {
                $schema = $this->serializer
                    ->getJsonSchema($stub_field, $context);
            }
            // Fallback basic annotations.
            if (empty($schema['title']) && ($title = $field->getLabel())) {
                $schema['title'] = (string) $title;
            }
            if (empty($schema['description']) && ($description = $field->getFieldStorageDefinition()
                ->getDescription())) {
                $schema['description'] = (string) $description;
            }
            if (in_array($field_name, $relationship_field_names, TRUE)) {
                $relationships_schema['properties'][$field_name] = $schema;
            }
            else {
                $attributes_schema['properties'][$field_name] = $schema;
            }
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function getSupportedTypes(?string $format) : array {
        return [
            ResourceObject::class => TRUE,
        ];
    }

}