#[HydraOperation] attriute

Author: Maxcastel

docs/guides/declare-hydra-operations.php

@@ -0,0 +1,68 @@
+<?php
+// ---
+// slug: declare-hydra-operations
+// name: Declare Hydra operations
+// position: 21
+// executable: false
+// tags: design, hydra, jsonld
+// ---
+
+namespace App\ApiResource {
+    use ApiPlatform\Metadata\ApiResource;
+    use ApiPlatform\Metadata\Get;
+    use ApiPlatform\Metadata\GetCollection;
+    use ApiPlatform\Metadata\HydraOperation;
+    use ApiPlatform\Metadata\Post;
+
+    // Issues are publicly readable and may be reported by any authenticated
+    // user. Only an administrator may delete an issue — and rather than
+    // exposing the DELETE operation globally on the resource (which would
+    // leak its existence to every consumer of the Hydra documentation), the
+    // operation is declared **per representation** with `#[HydraOperation]`.
+    //
+    // The `security` expression is evaluated when the issue is serialized; the
+    // expression has access to `object` (the current Issue), `user` (the
+    // current security token's user) and `request`.
+    #[ApiResource(
+        operations: [
+            new Get(),
+            new GetCollection(),
+            new Post(),
+        ],
+    )]
+    #[HydraOperation(
+        method: 'DELETE',
+        title: 'Delete this issue',
+        security: "is_granted('ROLE_ADMIN')",
+    )]
+    class Issue
+    {
+        public string $id;
+        public string $title;
+        public string $reporter;
+    }
+}
+
+// When an admin requests `/issues/42`, the JSON-LD response carries an extra
+// `hydra:operation` entry advertising the DELETE capability:
+//
+// ```json
+// {
+//   "@context": "/contexts/Issue",
+//   "@id": "/issues/42",
+//   "@type": "Issue",
+//   "title": "Login fails on Firefox",
+//   "reporter": "/users/7",
+//   "hydra:operation": [
+//     {
+//       "@type": ["hydra:Operation", "schema:DeleteAction"],
+//       "hydra:method": "DELETE",
+//       "hydra:title": "Delete this issue",
+//       "returns": "owl:Nothing"
+//     }
+//   ]
+// }
+// ```
+//
+// When the same resource is requested by a non-admin, the `hydra:operation`
+// property is omitted entirely.

phpstan.neon.dist

@@ -99,10 +99,6 @@ parameters:
 			message: '#^Service "[^"]+" is private.$#'
 			path: src
 
-		-
-			message: '#Access to an undefined property .*DocumentationNormalizer::\$resourceMetadataCollectionFactory#'
-			path: src/Hydra/Serializer/DocumentationNormalizer.php
-
 		# Allow extra assertions in tests: https://github.com/phpstan/phpstan-strict-rules/issues/130
 		- '#^Call to (static )?method PHPUnit\\Framework\\Assert::.* will always evaluate to true\.$#'
 

src/Hydra/Serializer/CollectionNormalizer.php

@@ -18,6 +18,7 @@
 use ApiPlatform\JsonLd\Serializer\JsonLdContextTrait;
 use ApiPlatform\Metadata\IriConverterInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\ResourceAccessCheckerInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
 use ApiPlatform\Metadata\UrlGeneratorInterface;
 use ApiPlatform\Serializer\AbstractCollectionNormalizer;
@@ -44,7 +45,7 @@ final class CollectionNormalizer extends AbstractCollectionNormalizer
         self::PRESERVE_COLLECTION_KEYS => false,
     ];
 
-    public function __construct(private readonly ContextBuilderInterface $contextBuilder, ResourceClassResolverInterface $resourceClassResolver, private readonly IriConverterInterface $iriConverter, array $defaultContext = [], private readonly ?ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null)
+    public function __construct(private readonly ContextBuilderInterface $contextBuilder, ResourceClassResolverInterface $resourceClassResolver, private readonly IriConverterInterface $iriConverter, array $defaultContext = [], private readonly ?ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory = null, private readonly ?ResourceAccessCheckerInterface $resourceAccessChecker = null)
     {
         $this->defaultContext = array_merge($this->defaultContext, $defaultContext);
 
@@ -72,15 +73,17 @@ protected function getPaginationData(iterable $object, array $context = []): arr
             $data[$hydraPrefix.'totalItems'] = \count($object);
         }
 
-        if (null !== $this->resourceMetadataCollectionFactory && ($context['hydra_operations'] ?? $this->defaultContext['hydra_operations'] ?? false)) {
-            $allHydraOperations = $this->getHydraOperationsFromResourceMetadatas(
+        if (null !== $this->resourceMetadataCollectionFactory) {
+            $hydraOperationsFromAttributes = $this->getHydraOperationsFromAttributes(
                 $resourceClass,
                 true,
+                null,
+                $context,
                 $hydraPrefix
             );
 
-            if (!empty($allHydraOperations)) {
-                $data[$hydraPrefix.'operation'] = $allHydraOperations;
+            if (!empty($hydraOperationsFromAttributes)) {
+                $data[$hydraPrefix.'operation'] = $hydraOperationsFromAttributes;
             }
         }
 

src/Hydra/Serializer/DocumentationNormalizer.php

@@ -25,6 +25,7 @@
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\ResourceAccessCheckerInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
 use ApiPlatform\Metadata\UrlGeneratorInterface;
 use ApiPlatform\Metadata\Util\TypeHelper;
@@ -51,6 +52,9 @@ final class DocumentationNormalizer implements NormalizerInterface
     use HydraPrefixTrait;
     public const FORMAT = 'jsonld';
 
+    private ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory;
+    private ?ResourceAccessCheckerInterface $resourceAccessChecker;
+
     public function __construct(
         private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory,
         private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory,
@@ -60,7 +64,10 @@ public function __construct(
         private readonly ?NameConverterInterface $nameConverter = null,
         private readonly ?array $defaultContext = [],
         private readonly ?bool $entrypointEnabled = true,
+        ?ResourceAccessCheckerInterface $resourceAccessChecker = null,
     ) {
+        $this->resourceMetadataCollectionFactory = $resourceMetadataFactory;
+        $this->resourceAccessChecker = $resourceAccessChecker;
     }
 
     /**

src/Hydra/Serializer/HydraOperationsTrait.php

@@ -17,27 +17,36 @@
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\CollectionOperationInterface;
 use ApiPlatform\Metadata\HttpOperation;
+use ApiPlatform\Metadata\HydraOperation;
+use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\ResourceAccessCheckerInterface;
 
 /**
  * Generates Hydra operations for JSON-LD responses.
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
+ *
+ * @property ResourceMetadataCollectionFactoryInterface|null $resourceMetadataCollectionFactory
+ * @property ResourceAccessCheckerInterface|null             $resourceAccessChecker
  */
 trait HydraOperationsTrait
 {
     /**
-     * Gets Hydra operations from all resource metadata.
+     * Gets Hydra operations from all HydraOperation attributes.
      */
-    private function getHydraOperationsFromResourceMetadatas(string $resourceClass, bool $collection, string $hydraPrefix = ContextBuilder::HYDRA_PREFIX): array
+    private function getHydraOperationsFromAttributes(string $resourceClass, bool $collection, ?object $object, array $context, string $hydraPrefix = ContextBuilder::HYDRA_PREFIX): array
     {
         $allHydraOperations = [];
         $operationNames = [];
 
         foreach ($this->resourceMetadataCollectionFactory->create($resourceClass) as $resourceMetadata) {
-            $hydraOperations = $this->getHydraOperationsFromResourceMetadata(
+            $hydraOperations = $this->getHydraOperationsFromAttributesForResource(
                 $collection,
                 $resourceMetadata,
                 $hydraPrefix,
+                $resourceClass,
+                $object,
+                $context,
                 $operationNames
             );
 
@@ -50,35 +59,117 @@ private function getHydraOperationsFromResourceMetadatas(string $resourceClass,
     /**
      * Gets Hydra operations from a single resource metadata.
      */
-    private function getHydraOperationsFromResourceMetadata(bool $collection, ApiResource $resourceMetadata, string $hydraPrefix, array &$operationNames): array
+    private function getHydraOperationsFromAttributesForResource(bool $collection, ApiResource $resourceMetadata, string $hydraPrefix, string $resourceClass, ?object $object, array $context, array &$operationNames): array
     {
         $operations = [];
-        $hydraOperations = $this->getHydraOperations(
-            $collection,
-            $resourceMetadata,
-            $hydraPrefix
-        );
-
-        if (!empty($hydraOperations)) {
-            foreach ($hydraOperations as $operation) {
-                $operationName = $operation[$hydraPrefix.'method'];
-                if (!\in_array($operationName, $operationNames, true)) {
-                    $operationNames[] = $operationName;
-                    $operations[] = $operation;
-                }
+
+        foreach ($resourceMetadata->getHydraOperations() ?? [] as $hydraOperation) {
+            if ($hydraOperation->getCollection() !== $collection) {
+                continue;
+            }
+
+            $method = $hydraOperation->getMethod();
+            if (\in_array($method, $operationNames, true)) {
+                continue;
+            }
+
+            if (!$this->isHydraOperationGranted($hydraOperation, $resourceClass, $object, $context)) {
+                continue;
             }
+
+            $operationNames[] = $method;
+            $operations[] = $this->normalizeHydraOperationAttribute($hydraOperation, $resourceMetadata->getShortName(), $hydraPrefix);
         }
 
         return $operations;
     }
 
+    private function isHydraOperationGranted(HydraOperation $hydraOperation, string $resourceClass, ?object $object, array $context): bool
+    {
+        if (null === $expression = $hydraOperation->getSecurity()) {
+            return true;
+        }
+
+        if (null === $this->resourceAccessChecker) {
+            return false;
+        }
+
+        $extraVariables = ['object' => $object];
+        if (isset($context['request'])) {
+            $extraVariables['request'] = $context['request'];
+        }
+
+        return $this->resourceAccessChecker->isGranted($resourceClass, $expression, $extraVariables);
+    }
+
+    /**
+     * Normalizes a HydraOperation attribute into a JSON-LD array.
+     */
+    private function normalizeHydraOperationAttribute(HydraOperation $hydraOperation, ?string $shortName, string $hydraPrefix = ContextBuilder::HYDRA_PREFIX): array
+    {
+        $method = $hydraOperation->getMethod();
+        $output = $hydraOperation->getExtraProperties();
+
+        $output['@type'] = $hydraOperation->getTypes() ?? $this->defaultHydraOperationTypes($method, $hydraPrefix);
+
+        if (null !== ($description = $hydraOperation->getDescription())) {
+            $output[$hydraPrefix.'description'] = $description;
+        }
+
+        if (null !== ($expects = $hydraOperation->getExpects())) {
+            $output['expects'] = $expects;
+        } elseif (\in_array($method, ['POST', 'PUT', 'PATCH'], true) && null !== $shortName) {
+            $output['expects'] = $shortName;
+        }
+
+        if (null !== ($returns = $hydraOperation->getReturns())) {
+            $output['returns'] = $returns;
+        } elseif ('DELETE' === $method) {
+            $output['returns'] = 'owl:Nothing';
+        } elseif (null !== $shortName) {
+            $output['returns'] = $shortName;
+        }
+
+        $output[$hydraPrefix.'method'] = $method;
+        $output[$hydraPrefix.'title'] = $hydraOperation->getTitle()
+            ?? $this->defaultHydraOperationTitle($method, $shortName, $hydraOperation->getCollection() && 'GET' === $method);
+
+        if (null === $output[$hydraPrefix.'title']) {
+            unset($output[$hydraPrefix.'title']);
+        }
+
+        ksort($output);
+
+        return $output;
+    }
+
+    private function defaultHydraOperationTypes(string $method, string $hydraPrefix): array|string
+    {
+        return match ($method) {
+            'GET' => [$hydraPrefix.'Operation', 'schema:FindAction'],
+            'POST' => [$hydraPrefix.'Operation', 'schema:CreateAction'],
+            'PUT' => [$hydraPrefix.'Operation', 'schema:ReplaceAction'],
+            'DELETE' => [$hydraPrefix.'Operation', 'schema:DeleteAction'],
+            default => $hydraPrefix.'Operation',
+        };
+    }
+
+    private function defaultHydraOperationTitle(string $method, ?string $shortName, bool $isCollection): ?string
+    {
+        if (null === $shortName) {
+            return null;
+        }
+
+        return strtolower($method).$shortName.($isCollection ? 'Collection' : '');
+    }
+
     /**
      * Gets Hydra operations.
      */
     private function getHydraOperations(bool $collection, ApiResource $resourceMetadata, string $hydraPrefix = ContextBuilder::HYDRA_PREFIX): array
     {
         $hydraOperations = [];
-        foreach ($resourceMetadata->getOperations() as $operation) {
+        foreach ($resourceMetadata->getOperations() ?? [] as $operation) {
             if (true === $operation->getHideHydraOperation()) {
                 continue;
             }
@@ -112,21 +203,22 @@ private function getHydraOperation(HttpOperation $operation, string $prefixedSho
         $inputClass = \array_key_exists('class', $inputMetadata) ? $inputMetadata['class'] : false;
         $outputClass = \array_key_exists('class', $outputMetadata) ? $outputMetadata['class'] : false;
 
-        if ('GET' === $method && $operation instanceof CollectionOperationInterface) {
+        $isCollection = $operation instanceof CollectionOperationInterface;
+
+        $hydraOperation += ['@type' => 'PATCH' === $method ? $hydraPrefix.'Operation' : $this->defaultHydraOperationTypes($method, $hydraPrefix)];
+
+        if ('GET' === $method && $isCollection) {
             $hydraOperation += [
-                '@type' => [$hydraPrefix.'Operation', 'schema:FindAction'],
                 $hydraPrefix.'description' => "Retrieves the collection of $shortName resources.",
                 'returns' => null === $outputClass ? 'owl:Nothing' : $hydraPrefix.'Collection',
             ];
         } elseif ('GET' === $method) {
             $hydraOperation += [
-                '@type' => [$hydraPrefix.'Operation', 'schema:FindAction'],
                 $hydraPrefix.'description' => "Retrieves a $shortName resource.",
                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
             ];
         } elseif ('PATCH' === $method) {
             $hydraOperation += [
-                '@type' => $hydraPrefix.'Operation',
                 $hydraPrefix.'description' => "Updates the $shortName resource.",
                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
@@ -144,28 +236,25 @@ private function getHydraOperation(HttpOperation $operation, string $prefixedSho
             }
         } elseif ('POST' === $method) {
             $hydraOperation += [
-                '@type' => [$hydraPrefix.'Operation', 'schema:CreateAction'],
                 $hydraPrefix.'description' => "Creates a $shortName resource.",
                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
             ];
         } elseif ('PUT' === $method) {
             $hydraOperation += [
-                '@type' => [$hydraPrefix.'Operation', 'schema:ReplaceAction'],
                 $hydraPrefix.'description' => "Replaces the $shortName resource.",
                 'returns' => null === $outputClass ? 'owl:Nothing' : $prefixedShortName,
                 'expects' => null === $inputClass ? 'owl:Nothing' : $prefixedShortName,
             ];
         } elseif ('DELETE' === $method) {
             $hydraOperation += [
-                '@type' => [$hydraPrefix.'Operation', 'schema:DeleteAction'],
                 $hydraPrefix.'description' => "Deletes the $shortName resource.",
                 'returns' => 'owl:Nothing',
             ];
         }
 
         $hydraOperation[$hydraPrefix.'method'] ??= $method;
-        $hydraOperation[$hydraPrefix.'title'] ??= strtolower($method).$shortName.($operation instanceof CollectionOperationInterface ? 'Collection' : '');
+        $hydraOperation[$hydraPrefix.'title'] ??= $this->defaultHydraOperationTitle($method, $shortName, $isCollection);
 
         ksort($hydraOperation);