feat(metadata): hide an hydra endpoint (draft)

src/Hydra/Serializer/DocumentationNormalizer.php

@@ -75,6 +75,10 @@ public function normalize(mixed $object, ?string $format = null, array $context
                 continue;
             }
 
+            if (true === $resourceMetadata->getHideHydraOperation()) {
+                continue;
+            }
+
             $shortName = $resourceMetadata->getShortName();
 
             $prefixedShortName = $resourceMetadata->getTypes()[0] ?? "#$shortName";
@@ -243,6 +247,10 @@ private function getHydraOperations(bool $collection, ?ResourceMetadataCollectio
         $hydraOperations = [];
         foreach ($resourceMetadataCollection as $resourceMetadata) {
             foreach ($resourceMetadata->getOperations() as $operation) {
+                if (true === $operation->getHideHydraOperation()) {
+                    continue;
+                }
+
                 if (('POST' === $operation->getMethod() || $operation instanceof CollectionOperationInterface) !== $collection) {
                     continue;
                 }

src/Hydra/Serializer/EntrypointNormalizer.php

@@ -56,7 +56,7 @@ public function normalize(mixed $object, ?string $format = null, array $context
 
                 foreach ($resource->getOperations() as $operation) {
                     $key = lcfirst($resource->getShortName());
-                    if (!$operation instanceof CollectionOperationInterface || isset($entrypoint[$key])) {
+                    if (true === $operation->getHideHydraOperation() || !$operation instanceof CollectionOperationInterface || isset($entrypoint[$key])) {
                         continue;
                     }
 

src/Metadata/ApiResource.php

@@ -964,6 +964,7 @@ public function __construct(
         array|string|null $middleware = null,
         array|Parameters|null $parameters = null,
         protected ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         protected array $extraProperties = [],
     ) {
         parent::__construct(
@@ -1009,6 +1010,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties
         );
 

src/Metadata/Delete.php

@@ -99,6 +99,7 @@ public function __construct(
         ?string $policy = null,
         array|string|null $middleware = null,
         ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -180,6 +181,7 @@ class: $class,
             collectDenormalizationErrors: $collectDenormalizationErrors,
             parameters: $parameters,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             stateOptions: $stateOptions,
         );
     }

src/Metadata/Extractor/XmlResourceExtractor.php

@@ -95,6 +95,7 @@ private function buildExtendedBase(\SimpleXMLElement $resource): array
             'exceptionToStatus' => $this->buildExceptionToStatus($resource),
             'queryParameterValidationEnabled' => $this->phpize($resource, 'queryParameterValidationEnabled', 'bool'),
             'strictQueryParameterValidation' => $this->phpize($resource, 'strictQueryParameterValidation', 'bool'),
+            'hideHydraOperation' => $this->phpize($resource, 'hideHydraOperation', 'bool'),
             'stateOptions' => $this->buildStateOptions($resource),
             'links' => $this->buildLinks($resource),
             'headers' => $this->buildHeaders($resource),

src/Metadata/Extractor/YamlResourceExtractor.php

@@ -339,6 +339,7 @@ private function buildOperations(array $resource, array $root): ?array
                 'serialize' => $this->phpize($operation, 'serialize', 'bool'),
                 'queryParameterValidate' => $this->phpize($operation, 'queryParameterValidate', 'bool'),
                 'strictQueryParameterValidation' => $this->phpize($operation, 'strictQueryParameterValidation', 'bool'),
+                'hideHydraOperation' => $this->phpize($resource, 'hideHydraOperation', 'bool'),
                 'priority' => $this->phpize($operation, 'priority', 'integer'),
                 'name' => $this->phpize($operation, 'name', 'string'),
                 'class' => (string) $class,

src/Metadata/Extractor/schema/resources.xsd

@@ -516,6 +516,7 @@
     <xsd:attributeGroup name="extendedBase">
         <xsd:attributeGroup ref="base"/>
         <xsd:attribute type="xsd:boolean" name="strictQueryParameterValidation"/>
+        <xsd:attribute type="xsd:boolean" name="hideHydraOperation"/>
         <xsd:attribute type="xsd:boolean" name="queryParameterValidationEnabled"/>
         <xsd:attribute type="xsd:string" name="routePrefix"/>
         <xsd:attribute type="xsd:boolean" name="stateless"/>

src/Metadata/Get.php

@@ -99,6 +99,7 @@ public function __construct(
         ?string $policy = null,
         array|string|null $middleware = null,
         ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -179,6 +180,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties,
         );
     }

src/Metadata/GetCollection.php

@@ -99,6 +99,7 @@ public function __construct(
         ?string $policy = null,
         array|string|null $middleware = null,
         ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         array $extraProperties = [],
         private ?string $itemUriTemplate = null,
     ) {
@@ -180,6 +181,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             stateOptions: $stateOptions,
         );
     }

src/Metadata/HttpOperation.php

@@ -156,6 +156,7 @@ public function __construct(
         protected ?array $links = null,
         protected ?array $errors = null,
         protected ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -259,6 +260,7 @@ class: $class,
             middleware: $middleware,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties
         );
     }

src/Metadata/Metadata.php

@@ -82,6 +82,7 @@ public function __construct(
         protected array|string|null $middleware = null,
         protected ?bool $queryParameterValidationEnabled = null,
         protected ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         protected array $extraProperties = [],
     ) {
         if (\is_array($parameters) && $parameters) {
@@ -680,4 +681,17 @@ public function withStrictQueryParameterValidation(bool $strictQueryParameterVal
 
         return $self;
     }
+
+    public function getHideHydraOperation(): ?bool
+    {
+        return $this->hideHydraOperation;
+    }
+
+    public function withHideHydraOperation(bool $hideHydraOperation): static
+    {
+        $self = clone $this;
+        $self->hideHydraOperation = $hideHydraOperation;
+
+        return $self;
+    }
 }

src/Metadata/Operation.php

@@ -812,6 +812,7 @@ public function __construct(
         array|string|null $middleware = null,
         ?bool $queryParameterValidationEnabled = null,
         protected ?bool $strictQueryParameterValidation = null,
+        protected ?bool $hideHydraOperation = null,
         protected array $extraProperties = [],
     ) {
         parent::__construct(
@@ -858,6 +859,7 @@ class: $class,
             middleware: $middleware,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties,
         );
     }

src/Metadata/Patch.php

@@ -99,6 +99,7 @@ public function __construct(
         ?string $policy = null,
         array|string|null $middleware = null,
         ?bool $strictQueryParameterValidation = null,
+        ?bool $hideHydraOperation = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -180,6 +181,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties
         );
     }

src/Metadata/Post.php

@@ -101,6 +101,7 @@ public function __construct(
         array $extraProperties = [],
         private ?string $itemUriTemplate = null,
         ?bool $strictQueryParameterValidation = null,
+        ?bool $hideHydraOperation = null,
     ) {
         parent::__construct(
             method: 'POST',
@@ -181,6 +182,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties
         );
     }

src/Metadata/Put.php

@@ -100,6 +100,7 @@ public function __construct(
         array|string|null $middleware = null,
         array $extraProperties = [],
         ?bool $strictQueryParameterValidation = null,
+        ?bool $hideHydraOperation = null,
         private ?bool $allowCreate = null,
     ) {
         parent::__construct(
@@ -181,6 +182,7 @@ class: $class,
             policy: $policy,
             middleware: $middleware,
             strictQueryParameterValidation: $strictQueryParameterValidation,
+            hideHydraOperation: $hideHydraOperation,
             extraProperties: $extraProperties
         );
     }

src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php

@@ -63,6 +63,7 @@ final class XmlResourceAdapter implements ResourceAdapterInterface
         'securityPostValidationMessage',
         'queryParameterValidationEnabled',
         'strictQueryParameterValidation',
+        'hideHydraOperation',
         'stateOptions',
         'collectDenormalizationErrors',
         'links',

src/Metadata/Tests/Extractor/ResourceMetadataCompatibilityTest.php

@@ -97,6 +97,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
             'securityPostValidationMessage' => 'Sorry, you must the owner of this resource to access it.',
             'queryParameterValidationEnabled' => true,
             'strictQueryParameterValidation' => false,
+            'hideHydraOperation' => false,
             'types' => ['someirischema', 'anotheririschema'],
             'formats' => [
                 'json' => null,
@@ -401,6 +402,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
                     ],
                     'queryParameterValidationEnabled' => false,
                     'strictQueryParameterValidation' => false,
+                    'hideHydraOperation' => false,
                     'read' => true,
                     'deserialize' => false,
                     'validate' => false,
@@ -489,6 +491,7 @@ final class ResourceMetadataCompatibilityTest extends TestCase
         'controller',
         'queryParameterValidationEnabled',
         'strictQueryParameterValidation',
+        'hideHydraOperation',
         'exceptionToStatus',
         'types',
         'formats',

src/Metadata/Tests/Extractor/XmlExtractorTest.php

@@ -67,6 +67,7 @@ public function testValidXML(): void
                     'securityPostValidationMessage' => null,
                     'queryParameterValidationEnabled' => null,
                     'strictQueryParameterValidation' => null,
+                    'hideHydraOperation' => null,
                     'input' => null,
                     'output' => null,
                     'types' => null,
@@ -138,6 +139,7 @@ public function testValidXML(): void
                     'securityPostValidationMessage' => null,
                     'queryParameterValidationEnabled' => null,
                     'strictQueryParameterValidation' => null,
+                    'hideHydraOperation' => null,
                     'input' => null,
                     'output' => null,
                     'types' => ['someirischema', 'anotheririschema'],
@@ -267,6 +269,7 @@ public function testValidXML(): void
                             'serialize' => null,
                             'queryParameterValidate' => null,
                             'strictQueryParameterValidation' => null,
+                            'hideHydraOperation' => null,
                             'collection' => null,
                             'method' => null,
                             'priority' => null,
@@ -371,6 +374,7 @@ public function testValidXML(): void
                             'serialize' => null,
                             'queryParameterValidate' => null,
                             'strictQueryParameterValidation' => null,
+                            'hideHydraOperation' => null,
                             'collection' => null,
                             'method' => null,
                             'priority' => null,

src/Metadata/Tests/Extractor/YamlExtractorTest.php

@@ -275,6 +275,7 @@ public function testValidYaml(): void
                             'securityPostValidationMessage' => null,
                             'queryParameterValidationEnabled' => null,
                             'strictQueryParameterValidation' => null,
+                            'hideHydraOperation' => null,
                             'input' => null,
                             'output' => null,
                             'types' => ['someirischema'],
@@ -355,6 +356,7 @@ public function testValidYaml(): void
                             'securityPostValidationMessage' => null,
                             'queryParameterValidationEnabled' => null,
                             'strictQueryParameterValidation' => null,
+                            'hideHydraOperation' => null,
                             'input' => null,
                             'output' => null,
                             'types' => ['anotheririschema'],

tests/Fixtures/TestBundle/ApiResource/HideHydraClass.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Tests\Fixtures\TestBundle\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+
+#[ApiResource(
+    hideHydraOperation: true,
+    normalizationContext: ['hydra_prefix' => false],
+    operations: [
+        new Get(),
+        new GetCollection(),
+    ]
+)]
+final class HideHydraClass
+{
+    public function __construct(public string $id, public string $title)
+    {
+    }
+}

tests/Fixtures/TestBundle/ApiResource/HideHydraOperation.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Tests\Fixtures\TestBundle\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+
+#[ApiResource(
+    normalizationContext: ['hydra_prefix' => false],
+    operations: [
+        new Get(hideHydraOperation: true),
+        new GetCollection(hideHydraOperation: true),
+    ]
+)]
+final class HideHydraOperation
+{
+    public function __construct(public string $id, public string $title)
+    {
+    }
+}