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

[papppeter]

Hi, @soyuka could you please send me a link to the docs please?
we would like to use this feature, but could not find the proper documentation.

(we tried to use it, but no provider registered message is comming up)