feat: BackedEnum resources

[GwendolenLynch]

Q	A
Branch?	main
Tickets	Closes #6298, closes #6317
License	MIT
Doc PR	api-platform/docs#...

Intended for 3.4, so now it is just for review.

Depends on #6288 as I want to refactor BackedEnumPlainResourceTest test methods into those classes.

• Add a provider for BackedEnums
• Identifier is value by default, and implementing function getId(), etc, works too
• Resource operations will default to only Get & GetCollection unless otherwise configured

#[ApiResource]
enum Status: int
{
    case DRAFT = 0;
    case PUBLISHED = 1;
}

GET /statuses

[
  {
    "name": "DRAFT",
    "value": 0
  },
  {
    "name": "PUBLISHED",
    "value": 1
  }
]

GET /statuses/1

{
  "name": "PUBLISHED",
  "value": 1
}

[soyuka]

would love to see json-ld supported, I need to add my commit to this at some point :)

[dunglas]

I would use URIs in GraphQL too, as we do for existing IDs and relations. WDYT?

[GwendolenLynch]

@dunglas it must be my week for getting confused. 🌞

I'm very happy to make required changes, but could you be so kind as to give a bit more context, please?

[gnito-org]

Please look at how I configure a backed enum as an API resource so that each instance has an IRI just like any other API resource.

https://github.com/gnito-org/problem-replicator-api-platform-enum-example

This is important for machine discovery of APIs and for consistency.

[GwendolenLynch]

Thank you @gnito-org, I can reproduce it here.

[soyuka]

@GwendolenLynch I merged #6288 could you rebase I this should fix some of the failing tests right?

[soyuka]

I'll continue working on this tomorrow, hopefully merging it!

[soyuka]

For the record @GwendolenLynch instead of decorating the provider chain, I choose to declare this as an operation provider instead. This will be called inside the ReadProvider:

core/src/State/Provider/ReadProvider.php

Lines 75 to 79 in ef4812a

	try {
	$data = $this->provider->provide($operation, $uriVariables, $context);
	} catch (ProviderNotFoundException $e) {
	$data = null;
	}

It's easier for userland to decorate our enum provider (or any item provider) instead of hooking into the main decoration chain.

[soyuka]

For further readers, this was duplicated from the BackedEnumTrait as graphql "guesses" the type from an union:

core/src/GraphQl/Type/FieldsBuilder.php

Lines 232 to 239 in ef4812a

	// guess union/intersect types: check each type until finding a valid one
	foreach ($propertyTypes as $propertyType) {
	if ($fieldConfiguration = $this->getResourceFieldConfiguration($property, $propertyMetadata->getDescription(), $propertyMetadata->getDeprecationReason(), $propertyType, $resourceClass, $input, $operation, $depth, null !== $propertyMetadata->getSecurity())) {
	$fields['id' === $property ? '_id' : $this->normalizePropertyName($property, $resourceClass)] = $fieldConfiguration;
	// stop at the first valid type
	break;
	}
	}

I'm not a huge fan, ideally we should provide a fix at some point there, even though when representing resources one should avoid scalar union types in my opinion.

[soyuka]

Thanks @GwendolenLynch!

[hafkenscheid]

This does not work if there are no GraphQlOperations