feat: add operation to hydra response

[Maxcastel]

Q	A
Branch?	main
Tickets	Closes #2588
License	MIT
Doc PR	api-platform/docs#2352

• By default, JSON-LD items and collections expose all the operations sharing their IRI in hydra:operation, filtered by their security. Disable it with serializer.hydra_operations: false, or per operation with hydraOperations: false.
• hydraOperations narrows the list with HydraOperation references: by name, or by method + uriTemplate. They are resolved when building the metadata and an unknown one throws. A reference can have its own security, otherwise the referenced operation's is used.
• Each operation is rendered like supportedOperation in the documentation.
• hideHydraOperation is docs-only: a hidden operation is still exposed to authorized users.

#[Get(uriTemplate: '/companies/{id}', hydraOperations: [new HydraOperation(method: 'DELETE')])]
#[Delete(uriTemplate: '/companies/{id}', security: "is_granted('ROLE_ADMIN')")]
class Company {}

GET /companies/1 as an admin (operation is omitted for other users):

{
  "@context": "/contexts/Company",
  "@id": "/companies/1",
  "@type": "Company",
  "operation": [
    {
      "@type": ["Operation", "schema:DeleteAction"],
      "description": "Deletes the Company resource.",
      "method": "DELETE",
      "returns": "owl:Nothing",
      "title": "deleteCompany"
    }
  ],
  "name": "Les-Tilleuls.coop"
}

[soyuka]

Mhh we shouldn't do it like this I think. We should keep the default operations, the ones available in a response are there to override or to add new operations capabilities to this resource. See the example at https://www.hydra-cg.com/spec/latest/core/#example-6-a-representation-of-an-issue-augmented-with-a-delete-operation

I'm not sure how users would be able to define this though as I guess that for these to appear the ideal usage would be to have conditions. For example you dont declare the hydra operation globally for DELETE but you choose to show it on the resource for admins.

We'd also need to patch the api-doc-parser to make this work on @api-platform/admin and related tools.

[Maxcastel]

@soyuka

#[HydraOperation] (986443a)
and/or
#[ApiResource(operations: [new Delete(security: "is_granted('ROLE_ADMIN')", hideHydraOperation: true)])] ?

Exemple:

#[ApiResource(operations: [
    new Get(),
    new GetCollection(),
    new Post(),
    new Delete(
        security: "is_granted('ROLE_ADMIN')",
        hideHydraOperation: true,
    ),
])]
#[HydraOperation(
    method: 'DELETE',
    security: "is_granted('ROLE_ADMIN')",
)]

?

[soyuka]

We need to simplify this approach, the idea with hydra:operation is that it exposes a related operation for discovery imo this should be an existing operation. For example:

#[Get(uriTemplate: '/companies', hydraOperations: [new HydraOperation(method: 'DELETE', uriTemplate: '/companies')])]

HydraOperation is only a reference, not a new operation, it's not an attribute either and it doesn't extend HttpOperation, just a small value object passed to hydraOperations. It points to an operation already declared on the resource, either by method + uriTemplate or by name. We resolve it when building the metadata, the method and IRI come from the referenced operation, and we throw if nothing matches so that a typo doesn't advertise a ghost operation. For the uriTemplate match we should reuse what we did in #8540 (format-agnostic), so /companies and /companies{._format} resolve to the same operation. It can have its own security to decide when it's exposed in the response, if not set we use the referenced operation's security.

When hydraOperations is not set, the default is all the available operations of the resource for the current IRI, filtered by their security at runtime. Setting it only narrows that list, false disables it.

hideHydraOperation stays docs-only: it removes the operation from supportedOperation but it can still be exposed in the response, that's how you hide something from the documentation and let authorized users discover it.

So the code should get a lot simpler: HydraOperation loses title, description, types, expects and returns since they're read from the referenced operation, #[HydraOperation] on the class goes away, and we don't need a second way to build the operation's JSON-LD, the response should reuse the one the DocumentationNormalizer already uses for supportedOperation. Thoughts?