PHP 8.1 Backed enums

[bpolaszek]

Hello there,

PHP 8.1 is on its way and will bring a long awaited feature: Enums.
As I'm really looking forward for that feature to land, I was wondering how Api-Platform will handle enums, and I didn't see any commit or PR related to that feature so far, so I wanted to start a discussion about this.

From my point of view,

• We should be able to list cases of an enum (GET / collection)
• We should be able to list "properties" of an enum (GET / item) - enums don't have properties (except read-only name and value - and I don't think exposing name is relevant) but they can have methods which can be exposed as properties through Symfony's serializer
• We should not be able to alter an enum (no POST / PUT / PATCH / DELETE - out of the box if possible)

I assume it should be easy to just add an ApiResource annotation on top of a Status enum to immediately expose:

• GET /api/statuses
• GET /api/statuses/{id}

Considering the following enum:

#[ApiResource]
enum Status: string
{
    case DRAFT = 'draft';
    case PUBLISHED = 'published';
}

I assume GET /api/statuses would return

{
  "@context": "/api/contexts/Status",
  "@id": "/api/statuses",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/api/statuses/draft",
      "@type": "Status",
      "value": "draft"
    },
    {
      "@id": "/api/statuses/published",
      "@type": "Status",
      "value": "published"
    }
  ]
}

Is that correct? Or do you plan to just return a list of values, like

{
  "@context": "\/api\/contexts\/Status",
  "@id": "\/api\/statuses",
  "@type": "hydra:Collection",
  "hydra:member": [
    "draft",
    "published"
  ]
}

?

I think the 1st one is more consistent, but that could also change the way we POST/PUT/PATCH entities.
Should we:

POST /api/posts
Content-Type: application/json

{
  "title": "foo",
  "status": "draft"
}

or

POST /api/posts
Content-Type: application/json

{
  "title": "foo",
  "status": "/api/statuses/draft"
}

?

I'm trying to get what direction you're taking on this so that I can anticipate a little on my developments - I'm working on something that will probably land on prod after PHP 8.1's release and I'd like the refactoring process to be as smooth as possible.

Maybe you already worked on this in background? WDYT?

Thanks!

NB: I'm only talking about backed enums here, I don't think normal enums can get in that scope.

[dunglas]

Hi, thanks for you detailed issue. Your proposal looks good to me, but we must double check that it's compatible with the standard way to express enumerations in RDF vocabularies and ontologies. Example in Schema.org: https://schema.org/Enumeration

Also, I think that we need to wait for the new metadata system @soyuka is working on before merging new features related to metadata (his first PR on this topic should be merged soon).

Cheers!

[soyuka]

#2254

[soyuka]

@bpolaszek doing some cleanup but I like your ideas, if needed let's talk about this again in #2254. 8.1 is now released we need to start by adding the php version to the CI and implement enum capabilities as it's now supported in the serializer (symfony/symfony#40241).
I think that the above can easily be implemented afterwards, let's add this to the #2254 list :).