vendor/api-platform/core/src/Hydra/Serializer/DocumentationNormalizer.php line 68

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of the API Platform project.
  5.  *
  6.  * (c) Kévin Dunglas <dunglas@gmail.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. declare(strict_types=1);
  14. namespace ApiPlatform\Hydra\Serializer;
  16. use ApiPlatform\Api\ResourceClassResolverInterface;
  17. use ApiPlatform\Api\UrlGeneratorInterface;
  18. use ApiPlatform\Core\Api\OperationMethodResolverInterface;
  19. use ApiPlatform\Core\Api\OperationType;
  20. use ApiPlatform\Core\Metadata\Property\Factory\PropertyMetadataFactoryInterface as LegacyPropertyMetadataFactoryInterface;
  21. use ApiPlatform\Core\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
  22. use ApiPlatform\Core\Metadata\Property\PropertyMetadata;
  23. use ApiPlatform\Core\Metadata\Property\SubresourceMetadata;
  24. use ApiPlatform\Core\Metadata\Resource\Factory\ResourceMetadataFactoryInterface;
  25. use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
  26. use ApiPlatform\Core\Operation\Factory\SubresourceOperationFactoryInterface;
  27. use ApiPlatform\Documentation\Documentation;
  28. use ApiPlatform\JsonLd\ContextBuilderInterface;
  29. use ApiPlatform\Metadata\ApiProperty;
  30. use ApiPlatform\Metadata\ApiResource;
  31. use ApiPlatform\Metadata\CollectionOperationInterface;
  32. use ApiPlatform\Metadata\HttpOperation;
  33. use ApiPlatform\Metadata\Operation;
  34. use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
  35. use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
  36. use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
  37. use Symfony\Component\PropertyInfo\Type;
  38. use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
  39. use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
  40. use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
  41. use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  43. /**
  44.  * Creates a machine readable Hydra API documentation.
  45.  *
  46.  * @author Kévin Dunglas <dunglas@gmail.com>
  47.  */
  48. final class DocumentationNormalizer implements NormalizerInterface, CacheableSupportsMethodInterface
  49. {
  50.     public const FORMAT = 'jsonld';
  52.     /**
  53.      * @var ResourceMetadataFactoryInterface|ResourceMetadataCollectionFactoryInterface
  54.      */
  55.     private $resourceMetadataFactory;
  56.     private $propertyNameCollectionFactory;
  58.     /**
  59.      * @var PropertyMetadataFactoryInterface|LegacyPropertyMetadataFactoryInterface
  60.      */
  61.     private $propertyMetadataFactory;
  62.     private $resourceClassResolver;
  63.     private $operationMethodResolver;
  64.     private $urlGenerator;
  65.     private $subresourceOperationFactory;
  66.     private $nameConverter;
  68.     public function __construct($resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver = null, UrlGeneratorInterface $urlGenerator, SubresourceOperationFactoryInterface $subresourceOperationFactory = null, NameConverterInterface $nameConverter = null)
  69.     {
  70.         if ($operationMethodResolver) {
  71.             @trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.5 and will be removed in 3.0.', OperationMethodResolverInterface::class, __METHOD__), \E_USER_DEPRECATED);
  72.         }
  74.         $this->resourceMetadataFactory = $resourceMetadataFactory;
  76.         if (!$resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  77.             trigger_deprecation('api-platform/core', '2.7', sprintf('Use "%s" instead of "%s".', ResourceMetadataCollectionFactoryInterface::class, ResourceMetadataFactoryInterface::class));
  78.         }
  80.         if ($subresourceOperationFactory) {
  81.             trigger_deprecation('api-platform/core', '2.7', sprintf('Using "%s" is deprecated and will be removed.', SubresourceOperationFactoryInterface::class));
  82.         }
  84.         $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
  85.         $this->propertyMetadataFactory = $propertyMetadataFactory;
  86.         $this->resourceClassResolver = $resourceClassResolver;
  87.         $this->operationMethodResolver = $operationMethodResolver;
  88.         $this->urlGenerator = $urlGenerator;
  89.         $this->subresourceOperationFactory = $subresourceOperationFactory;
  90.         $this->nameConverter = $nameConverter;
  91.     }
  93.     /**
  94.      * @param mixed|null $format
  95.      *
  96.      * @return array|string|int|float|bool|\ArrayObject|null
  97.      */
  98.     public function normalize($object, $format = null, array $context = [])
  99.     {
  100.         $classes = [];
  101.         $entrypointProperties = [];
  103.         foreach ($object->getResourceNameCollection() as $resourceClass) {
  104.             $resourceMetadataCollection = $this->resourceMetadataFactory->create($resourceClass);
  106.             if ($resourceMetadataCollection instanceof ResourceMetadata) {
  107.                 $shortName = $resourceMetadataCollection->getShortName();
  108.                 $prefixedShortName = $resourceMetadataCollection->getIri() ?? "#$shortName";
  110.                 $this->populateEntrypointProperties($resourceClass, $resourceMetadataCollection, $shortName, $prefixedShortName, $entrypointProperties);
  111.                 $classes[] = $this->getClass($resourceClass, $resourceMetadataCollection, $shortName, $prefixedShortName, $context);
  112.                 continue;
  113.             }
  115.             $resourceMetadata = $resourceMetadataCollection[0];
  116.             $shortName = $resourceMetadata->getShortName();
  117.             $prefixedShortName = $resourceMetadata->getTypes()[0] ?? "#$shortName";
  118.             $this->populateEntrypointProperties($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $entrypointProperties, $resourceMetadataCollection);
  119.             $classes[] = $this->getClass($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context, $resourceMetadataCollection);
  120.         }
  122.         return $this->computeDoc($object, $this->getClasses($entrypointProperties, $classes));
  123.     }
  125.     /**
  126.      * Populates entrypoint properties.
  127.      *
  128.      * @param ResourceMetadata|ApiResource $resourceMetadata
  129.      */
  130.     private function populateEntrypointProperties(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array &$entrypointProperties, ResourceMetadataCollection $resourceMetadataCollection = null)
  131.     {
  132.         $hydraCollectionOperations = $this->getHydraOperations($resourceClass, $resourceMetadata, $prefixedShortName, true, $resourceMetadataCollection);
  133.         if (empty($hydraCollectionOperations)) {
  134.             return;
  135.         }
  137.         $entrypointProperty = [
  138.             '@type' => 'hydra:SupportedProperty',
  139.             'hydra:property' => [
  140.                 '@id' => sprintf('#Entrypoint/%s', lcfirst($shortName)),
  141.                 '@type' => 'hydra:Link',
  142.                 'domain' => '#Entrypoint',
  143.                 'rdfs:label' => "The collection of $shortName resources",
  144.                 'rdfs:range' => [
  145.                     ['@id' => 'hydra:Collection'],
  146.                     [
  147.                         'owl:equivalentClass' => [
  148.                             'owl:onProperty' => ['@id' => 'hydra:member'],
  149.                             'owl:allValuesFrom' => ['@id' => $prefixedShortName],
  150.                         ],
  151.                     ],
  152.                 ],
  153.                 'hydra:supportedOperation' => $hydraCollectionOperations,
  154.             ],
  155.             'hydra:title' => "The collection of $shortName resources",
  156.             'hydra:readable' => true,
  157.             'hydra:writeable' => false,
  158.         ];
  160.         if ($resourceMetadata instanceof ResourceMetadata ? $resourceMetadata->getCollectionOperationAttribute('GET', 'deprecation_reason', null, true) : $resourceMetadata->getDeprecationReason()) {
  161.             $entrypointProperty['owl:deprecated'] = true;
  162.         }
  164.         $entrypointProperties[] = $entrypointProperty;
  165.     }
  167.     /**
  168.      * Gets a Hydra class.
  169.      *
  170.      * @param ResourceMetadata|ApiResource $resourceMetadata
  171.      */
  172.     private function getClass(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array $context, ResourceMetadataCollection $resourceMetadataCollection = null): array
  173.     {
  174.         if ($resourceMetadata instanceof ApiResource) {
  175.             $description = $resourceMetadata->getDescription();
  176.             $isDeprecated = $resourceMetadata->getDeprecationReason();
  177.         } else {
  178.             $description = $resourceMetadata->getDescription();
  179.             $isDeprecated = $resourceMetadata->getAttribute('deprecation_reason');
  180.         }
  182.         $class = [
  183.             '@id' => $prefixedShortName,
  184.             '@type' => 'hydra:Class',
  185.             'rdfs:label' => $shortName,
  186.             'hydra:title' => $shortName,
  187.             'hydra:supportedProperty' => $this->getHydraProperties($resourceClass, $resourceMetadata, $shortName, $prefixedShortName, $context),
  188.             'hydra:supportedOperation' => $this->getHydraOperations($resourceClass, $resourceMetadata, $prefixedShortName, false, $resourceMetadataCollection),
  189.         ];
  191.         if (null !== $description) {
  192.             $class['hydra:description'] = $description;
  193.         }
  195.         if ($isDeprecated) {
  196.             $class['owl:deprecated'] = true;
  197.         }
  199.         return $class;
  200.     }
  202.     /**
  203.      * Gets the context for the property name factory.
  204.      */
  205.     private function getPropertyNameCollectionFactoryContext(ResourceMetadata $resourceMetadata): array
  206.     {
  207.         $attributes = $resourceMetadata->getAttributes();
  208.         $context = [];
  210.         if (isset($attributes['normalization_context'][AbstractNormalizer::GROUPS])) {
  211.             $context['serializer_groups'] = (array) $attributes['normalization_context'][AbstractNormalizer::GROUPS];
  212.         }
  214.         if (!isset($attributes['denormalization_context'][AbstractNormalizer::GROUPS])) {
  215.             return $context;
  216.         }
  218.         if (isset($context['serializer_groups'])) {
  219.             foreach ((array) $attributes['denormalization_context'][AbstractNormalizer::GROUPS] as $groupName) {
  220.                 $context['serializer_groups'][] = $groupName;
  221.             }
  223.             return $context;
  224.         }
  226.         $context['serializer_groups'] = (array) $attributes['denormalization_context'][AbstractNormalizer::GROUPS];
  228.         return $context;
  229.     }
  231.     /**
  232.      * Creates context for property metatata factories.
  233.      */
  234.     private function getPropertyMetadataFactoryContext(ApiResource $resourceMetadata): array
  235.     {
  236.         $normalizationGroups = $resourceMetadata->getNormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  237.         $denormalizationGroups = $resourceMetadata->getDenormalizationContext()[AbstractNormalizer::GROUPS] ?? null;
  238.         $propertyContext = [
  239.             'normalization_groups' => $normalizationGroups,
  240.             'denormalization_groups' => $denormalizationGroups,
  241.         ];
  242.         $propertyNameContext = [];
  244.         if ($normalizationGroups) {
  245.             $propertyNameContext['serializer_groups'] = $normalizationGroups;
  246.         }
  248.         if (!$denormalizationGroups) {
  249.             return [$propertyNameContext, $propertyContext];
  250.         }
  252.         if (!isset($propertyNameContext['serializer_groups'])) {
  253.             $propertyNameContext['serializer_groups'] = $denormalizationGroups;
  255.             return [$propertyNameContext, $propertyContext];
  256.         }
  258.         foreach ($denormalizationGroups as $group) {
  259.             $propertyNameContext['serializer_groups'][] = $group;
  260.         }
  262.         return [$propertyNameContext, $propertyContext];
  263.     }
  265.     /**
  266.      * Gets Hydra properties.
  267.      *
  268.      * @param ResourceMetadata|ApiResource $resourceMetadata
  269.      */
  270.     private function getHydraProperties(string $resourceClass, $resourceMetadata, string $shortName, string $prefixedShortName, array $context): array
  271.     {
  272.         $classes = [];
  274.         if ($resourceMetadata instanceof ResourceMetadata) {
  275.             foreach ($resourceMetadata->getCollectionOperations() as $operationName => $operation) {
  276.                 $inputMetadata = $resourceMetadata->getTypedOperationAttribute(OperationType::COLLECTION, $operationName, 'input', ['class' => $resourceClass], true);
  277.                 if (null !== $inputClass = $inputMetadata['class'] ?? null) {
  278.                     $classes[$inputClass] = true;
  279.                 }
  281.                 $outputMetadata = $resourceMetadata->getTypedOperationAttribute(OperationType::COLLECTION, $operationName, 'output', ['class' => $resourceClass], true);
  282.                 if (null !== $outputClass = $outputMetadata['class'] ?? null) {
  283.                     $classes[$outputClass] = true;
  284.                 }
  285.             }
  286.         } else {
  287.             $classes[$resourceClass] = true;
  288.             foreach ($resourceMetadata->getOperations() as $operation) {
  289.                 /** @var Operation $operation */
  290.                 if (!$operation instanceof CollectionOperationInterface) {
  291.                     continue;
  292.                 }
  294.                 $inputMetadata = $operation->getInput();
  295.                 if (null !== $inputClass = $inputMetadata['class'] ?? null) {
  296.                     $classes[$inputClass] = true;
  297.                 }
  299.                 $outputMetadata = $operation->getOutput();
  300.                 if (null !== $outputClass = $outputMetadata['class'] ?? null) {
  301.                     $classes[$outputClass] = true;
  302.                 }
  303.             }
  304.         }
  306.         /** @var string[] $classes */
  307.         $classes = array_keys($classes);
  308.         $properties = [];
  309.         if ($resourceMetadata instanceof ResourceMetadata) {
  310.             $propertyNameContext = $this->getPropertyNameCollectionFactoryContext($resourceMetadata);
  311.             $propertyContext = [];
  312.         } else {
  313.             [$propertyNameContext, $propertyContext] = $this->getPropertyMetadataFactoryContext($resourceMetadata);
  314.         }
  316.         foreach ($classes as $class) {
  317.             foreach ($this->propertyNameCollectionFactory->create($class, $propertyNameContext) as $propertyName) {
  318.                 $propertyMetadata = $this->propertyMetadataFactory->create($class, $propertyName, $propertyContext);
  320.                 if (true === $propertyMetadata->isIdentifier() && false === $propertyMetadata->isWritable()) {
  321.                     continue;
  322.                 }
  324.                 if ($this->nameConverter) {
  325.                     $propertyName = $this->nameConverter->normalize($propertyName, $class, self::FORMAT, $context);
  326.                 }
  328.                 $properties[] = $this->getProperty($propertyMetadata, $propertyName, $prefixedShortName, $shortName);
  329.             }
  330.         }
  332.         return $properties;
  333.     }
  335.     /**
  336.      * Gets Hydra operations.
  337.      *
  338.      * @param ResourceMetadata|ApiResource $resourceMetadata
  339.      */
  340.     private function getHydraOperations(string $resourceClass, $resourceMetadata, string $prefixedShortName, bool $collection, ResourceMetadataCollection $resourceMetadataCollection = null): array
  341.     {
  342.         if ($resourceMetadata instanceof ResourceMetadata) {
  343.             if (null === $operations = $collection ? $resourceMetadata->getCollectionOperations() : $resourceMetadata->getItemOperations()) {
  344.                 return [];
  345.             }
  347.             $hydraOperations = [];
  348.             foreach ($operations as $operationName => $operation) {
  349.                 $hydraOperations[] = $this->getHydraOperation($resourceClass, $resourceMetadata, $operationName, $operation, $prefixedShortName, $collection ? OperationType::COLLECTION : OperationType::ITEM);
  350.             }
  351.         } else {
  352.             $hydraOperations = [];
  353.             foreach ($resourceMetadataCollection as $resourceMetadata) {
  354.                 foreach ($resourceMetadata->getOperations() as $operationName => $operation) {
  355.                     if ((HttpOperation::METHOD_POST === $operation->getMethod() || $operation instanceof CollectionOperationInterface) !== $collection) {
  356.                         continue;
  357.                     }
  359.                     $hydraOperations[] = $this->getHydraOperation($resourceClass, $resourceMetadata, $operationName, $operation, $operation->getTypes()[0] ?? "#{$operation->getShortName()}", null);
  360.                 }
  361.             }
  362.         }
  364.         if (null !== $this->subresourceOperationFactory && !$this->resourceMetadataFactory instanceof ResourceMetadataCollectionFactoryInterface) {
  365.             foreach ($this->subresourceOperationFactory->create($resourceClass) as $operationId => $operation) {
  366.                 $subresourceMetadata = $this->resourceMetadataFactory->create($operation['resource_class']);
  367.                 $propertyMetadata = $this->propertyMetadataFactory->create(end($operation['identifiers'])[0], $operation['property']);
  368.                 $hydraOperations[] = $this->getHydraOperation($resourceClass, $subresourceMetadata, $operation['route_name'], $operation, "#{$subresourceMetadata->getShortName()}", OperationType::SUBRESOURCE, $propertyMetadata->getSubresource());
  369.             }
  370.         }
  372.         return $hydraOperations;
  373.     }
  375.     /**
  376.      * Gets and populates if applicable a Hydra operation.
  377.      *
  378.      * @param ResourceMetadata|ApiResource $resourceMetadata
  379.      * @param array|HttpOperation          $operation
  380.      */
  381.     private function getHydraOperation(string $resourceClass, $resourceMetadata, string $operationName, $operation, string $prefixedShortName, string $operationType = null, SubresourceMetadata $subresourceMetadata = null): array
  382.     {
  383.         if ($operation instanceof HttpOperation) {
  384.             $method = $operation->getMethod() ?: HttpOperation::METHOD_GET;
  385.         } elseif ($this->operationMethodResolver) {
  386.             if (OperationType::COLLECTION === $operationType) {
  387.                 $method = $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
  388.             } elseif (OperationType::ITEM === $operationType) {
  389.                 $method = $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName);
  390.             } else {
  391.                 $method = 'GET';
  392.             }
  393.         } else {
  394.             $method = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'method', 'GET');
  395.         }
  397.         $hydraOperation = $operation instanceof HttpOperation ? ($operation->getHydraContext() ?? []) : ($operation['hydra_context'] ?? []);
  398.         if ($operation instanceof HttpOperation ? $operation->getDeprecationReason() : $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
  399.             $hydraOperation['owl:deprecated'] = true;
  400.         }
  402.         if ($operation instanceof HttpOperation) {
  403.             $shortName = $operation->getShortName();
  404.             $inputMetadata = $operation->getInput() ?? [];
  405.             $outputMetadata = $operation->getOutput() ?? [];
  406.             $operationType = $operation instanceof CollectionOperationInterface ? OperationType::COLLECTION : OperationType::ITEM;
  407.         } else {
  408.             $shortName = $resourceMetadata->getShortName();
  409.             $inputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'input', ['class' => false]);
  410.             $outputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output', ['class' => false]);
  411.         }
  413.         $inputClass = \array_key_exists('class', $inputMetadata) ? $inputMetadata['class'] : false;
  414.         $outputClass = \array_key_exists('class', $outputMetadata) ? $outputMetadata['class'] : false;
  416.         if ('GET' === $method && OperationType::COLLECTION === $operationType) {
  417.             $hydraOperation += [
  418.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  419.                 'hydra:title' => "Retrieves the collection of $shortName resources.",
  420.                 'returns' => 'hydra:Collection',
  421.             ];
  422.         } elseif ('GET' === $method && OperationType::SUBRESOURCE === $operationType) {
  423.             $hydraOperation += [
  424.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  425.                 'hydra:title' => $subresourceMetadata && $subresourceMetadata->isCollection() ? "Retrieves the collection of $shortName resources." : "Retrieves a $shortName resource.",
  426.                 'returns' => null === $outputClass ? 'owl:Nothing' : "#$shortName",
  427.             ];
  428.         } elseif ('GET' === $method) {
  429.             $hydraOperation += [
  430.                 '@type' => ['hydra:Operation', 'schema:FindAction'],
  431.                 'hydra:title' => "Retrieves a $shortName resource.",
  432.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  433.             ];
  434.         } elseif ('PATCH' === $method) {
  435.             $hydraOperation += [
  436.                 '@type' => 'hydra:Operation',
  437.                 'hydra:title' => "Updates the $shortName resource.",
  438.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  439.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  440.             ];
  441.         } elseif ('POST' === $method) {
  442.             $hydraOperation += [
  443.                 '@type' => ['hydra:Operation', 'schema:CreateAction'],
  444.                 'hydra:title' => "Creates a $shortName resource.",
  445.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  446.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  447.             ];
  448.         } elseif ('PUT' === $method) {
  449.             $hydraOperation += [
  450.                 '@type' => ['hydra:Operation', 'schema:ReplaceAction'],
  451.                 'hydra:title' => "Replaces the $shortName resource.",
  452.                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
  453.                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
  454.             ];
  455.         } elseif ('DELETE' === $method) {
  456.             $hydraOperation += [
  457.                 '@type' => ['hydra:Operation', 'schema:DeleteAction'],
  458.                 'hydra:title' => "Deletes the $shortName resource.",
  459.                 'returns' => 'owl:Nothing',
  460.             ];
  461.         }
  463.         $hydraOperation['hydra:method'] ?? $hydraOperation['hydra:method'] = $method;
  465.         if (!isset($hydraOperation['rdfs:label']) && isset($hydraOperation['hydra:title'])) {
  466.             $hydraOperation['rdfs:label'] = $hydraOperation['hydra:title'];
  467.         }
  469.         ksort($hydraOperation);
  471.         return $hydraOperation;
  472.     }
  474.     /**
  475.      * Gets the range of the property.
  476.      *
  477.      * @param ApiProperty|PropertyMetadata $propertyMetadata
  478.      */
  479.     private function getRange($propertyMetadata): ?string
  480.     {
  481.         $jsonldContext = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttributes()['jsonld_context'] ?? [] : $propertyMetadata->getJsonldContext();
  483.         if (isset($jsonldContext['@type'])) {
  484.             return $jsonldContext['@type'];
  485.         }
  487.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  488.         $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  489.         if (null === $type) {
  490.             return null;
  491.         }
  493.         if ($type->isCollection() && null !== $collectionType = method_exists(Type::class, 'getCollectionValueTypes') ? ($type->getCollectionValueTypes()[0] ?? null) : $type->getCollectionValueType()) {
  494.             $type = $collectionType;
  495.         }
  497.         switch ($type->getBuiltinType()) {
  498.             case Type::BUILTIN_TYPE_STRING:
  499.                 return 'xmls:string';
  500.             case Type::BUILTIN_TYPE_INT:
  501.                 return 'xmls:integer';
  502.             case Type::BUILTIN_TYPE_FLOAT:
  503.                 return 'xmls:decimal';
  504.             case Type::BUILTIN_TYPE_BOOL:
  505.                 return 'xmls:boolean';
  506.             case Type::BUILTIN_TYPE_OBJECT:
  507.                 if (null === $className = $type->getClassName()) {
  508.                     return null;
  509.                 }
  511.                 if (is_a($className, \DateTimeInterface::class, true)) {
  512.                     return 'xmls:dateTime';
  513.                 }
  515.                 if ($this->resourceClassResolver->isResourceClass($className)) {
  516.                     $resourceMetadata = $this->resourceMetadataFactory->create($className);
  517.                     if ($resourceMetadata instanceof ResourceMetadataCollection) {
  518.                         $operation = $resourceMetadata->getOperation();
  520.                         if (!$operation instanceof HttpOperation) {
  521.                             return "#{$operation->getShortName()}";
  522.                         }
  524.                         return $operation->getTypes()[0] ?? "#{$operation->getShortName()}";
  525.                     }
  527.                     return $resourceMetadata->getIri() ?? "#{$resourceMetadata->getShortName()}";
  528.                 }
  529.         }
  531.         return null;
  532.     }
  534.     /**
  535.      * Builds the classes array.
  536.      */
  537.     private function getClasses(array $entrypointProperties, array $classes): array
  538.     {
  539.         $classes[] = [
  540.             '@id' => '#Entrypoint',
  541.             '@type' => 'hydra:Class',
  542.             'hydra:title' => 'The API entrypoint',
  543.             'hydra:supportedProperty' => $entrypointProperties,
  544.             'hydra:supportedOperation' => [
  545.                 '@type' => 'hydra:Operation',
  546.                 'hydra:method' => 'GET',
  547.                 'rdfs:label' => 'The API entrypoint.',
  548.                 'returns' => '#EntryPoint',
  549.             ],
  550.         ];
  552.         // Constraint violation
  553.         $classes[] = [
  554.             '@id' => '#ConstraintViolation',
  555.             '@type' => 'hydra:Class',
  556.             'hydra:title' => 'A constraint violation',
  557.             'hydra:supportedProperty' => [
  558.                 [
  559.                     '@type' => 'hydra:SupportedProperty',
  560.                     'hydra:property' => [
  561.                         '@id' => '#ConstraintViolation/propertyPath',
  562.                         '@type' => 'rdf:Property',
  563.                         'rdfs:label' => 'propertyPath',
  564.                         'domain' => '#ConstraintViolation',
  565.                         'range' => 'xmls:string',
  566.                     ],
  567.                     'hydra:title' => 'propertyPath',
  568.                     'hydra:description' => 'The property path of the violation',
  569.                     'hydra:readable' => true,
  570.                     'hydra:writeable' => false,
  571.                 ],
  572.                 [
  573.                     '@type' => 'hydra:SupportedProperty',
  574.                     'hydra:property' => [
  575.                         '@id' => '#ConstraintViolation/message',
  576.                         '@type' => 'rdf:Property',
  577.                         'rdfs:label' => 'message',
  578.                         'domain' => '#ConstraintViolation',
  579.                         'range' => 'xmls:string',
  580.                     ],
  581.                     'hydra:title' => 'message',
  582.                     'hydra:description' => 'The message associated with the violation',
  583.                     'hydra:readable' => true,
  584.                     'hydra:writeable' => false,
  585.                 ],
  586.             ],
  587.         ];
  589.         // Constraint violation list
  590.         $classes[] = [
  591.             '@id' => '#ConstraintViolationList',
  592.             '@type' => 'hydra:Class',
  593.             'subClassOf' => 'hydra:Error',
  594.             'hydra:title' => 'A constraint violation list',
  595.             'hydra:supportedProperty' => [
  596.                 [
  597.                     '@type' => 'hydra:SupportedProperty',
  598.                     'hydra:property' => [
  599.                         '@id' => '#ConstraintViolationList/violations',
  600.                         '@type' => 'rdf:Property',
  601.                         'rdfs:label' => 'violations',
  602.                         'domain' => '#ConstraintViolationList',
  603.                         'range' => '#ConstraintViolation',
  604.                     ],
  605.                     'hydra:title' => 'violations',
  606.                     'hydra:description' => 'The violations',
  607.                     'hydra:readable' => true,
  608.                     'hydra:writeable' => false,
  609.                 ],
  610.             ],
  611.         ];
  613.         return $classes;
  614.     }
  616.     /**
  617.      * Gets a property definition.
  618.      *
  619.      * @param ApiProperty|PropertyMetadata $propertyMetadata
  620.      */
  621.     private function getProperty($propertyMetadata, string $propertyName, string $prefixedShortName, string $shortName): array
  622.     {
  623.         if ($propertyMetadata instanceof PropertyMetadata) {
  624.             $iri = $propertyMetadata->getIri();
  625.         } else {
  626.             if ($iri = $propertyMetadata->getIris()) {
  627.                 $iri = 1 === \count($iri) ? $iri[0] : $iri;
  628.             }
  629.         }
  631.         if (!isset($iri)) {
  632.             $iri = "#$shortName/$propertyName";
  633.         }
  635.         $propertyData = [
  636.             '@id' => $iri,
  637.             '@type' => false === $propertyMetadata->isReadableLink() ? 'hydra:Link' : 'rdf:Property',
  638.             'rdfs:label' => $propertyName,
  639.             'domain' => $prefixedShortName,
  640.         ];
  642.         // TODO: 3.0 support multiple types, default value of types will be [] instead of null
  643.         $type = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getType() : $propertyMetadata->getBuiltinTypes()[0] ?? null;
  645.         if (null !== $type && !$type->isCollection() && (null !== $className = $type->getClassName()) && $this->resourceClassResolver->isResourceClass($className)) {
  646.             $propertyData['owl:maxCardinality'] = 1;
  647.         }
  649.         $property = [
  650.             '@type' => 'hydra:SupportedProperty',
  651.             'hydra:property' => $propertyData,
  652.             'hydra:title' => $propertyName,
  653.             'hydra:required' => $propertyMetadata->isRequired(),
  654.             'hydra:readable' => $propertyMetadata->isReadable(),
  655.             'hydra:writeable' => $propertyMetadata->isWritable() || $propertyMetadata->isInitializable(),
  656.         ];
  658.         if (null !== $range = $this->getRange($propertyMetadata)) {
  659.             $property['hydra:property']['range'] = $range;
  660.         }
  662.         if (null !== $description = $propertyMetadata->getDescription()) {
  663.             $property['hydra:description'] = $description;
  664.         }
  666.         if ($deprecationReason = $propertyMetadata instanceof PropertyMetadata ? $propertyMetadata->getAttribute('deprecation_reason') : $propertyMetadata->getDeprecationReason()) {
  667.             $property['owl:deprecated'] = true;
  668.         }
  670.         return $property;
  671.     }
  673.     /**
  674.      * Computes the documentation.
  675.      */
  676.     private function computeDoc(Documentation $object, array $classes): array
  677.     {
  678.         $doc = ['@context' => $this->getContext(), '@id' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT]), '@type' => 'hydra:ApiDocumentation'];
  680.         if ('' !== $object->getTitle()) {
  681.             $doc['hydra:title'] = $object->getTitle();
  682.         }
  684.         if ('' !== $object->getDescription()) {
  685.             $doc['hydra:description'] = $object->getDescription();
  686.         }
  688.         $doc['hydra:entrypoint'] = $this->urlGenerator->generate('api_entrypoint');
  689.         $doc['hydra:supportedClass'] = $classes;
  691.         return $doc;
  692.     }
  694.     /**
  695.      * Builds the JSON-LD context for the API documentation.
  696.      */
  697.     private function getContext(): array
  698.     {
  699.         return [
  700.             '@vocab' => $this->urlGenerator->generate('api_doc', ['_format' => self::FORMAT], UrlGeneratorInterface::ABS_URL).'#',
  701.             'hydra' => ContextBuilderInterface::HYDRA_NS,
  702.             'rdf' => ContextBuilderInterface::RDF_NS,
  703.             'rdfs' => ContextBuilderInterface::RDFS_NS,
  704.             'xmls' => ContextBuilderInterface::XML_NS,
  705.             'owl' => ContextBuilderInterface::OWL_NS,
  706.             'schema' => ContextBuilderInterface::SCHEMA_ORG_NS,
  707.             'domain' => ['@id' => 'rdfs:domain', '@type' => '@id'],
  708.             'range' => ['@id' => 'rdfs:range', '@type' => '@id'],
  709.             'subClassOf' => ['@id' => 'rdfs:subClassOf', '@type' => '@id'],
  710.             'expects' => ['@id' => 'hydra:expects', '@type' => '@id'],
  711.             'returns' => ['@id' => 'hydra:returns', '@type' => '@id'],
  712.         ];
  713.     }
  715.     public function supportsNormalization($data, $format = null, array $context = []): bool
  716.     {
  717.         return self::FORMAT === $format && $data instanceof Documentation;
  718.     }
  720.     public function hasCacheableSupportsMethod(): bool
  721.     {
  722.         return true;
  723.     }
  724. }
  726. class_alias(DocumentationNormalizer::class, \ApiPlatform\Core\Hydra\Serializer\DocumentationNormalizer::class);