document enums as resource

Author: soyuka

core/enums.md

@@ -0,0 +1,281 @@
+# Enums as API Resources
+
+API Platform provides support for PHP 8.1+ `BackedEnum`s, allowing them to be exposed as first-class API resources. This enables clients to discover available enum cases and their associated metadata directly through your API.
+
+## Exposing BackedEnums
+
+To expose a `BackedEnum` as an API resource, simply apply the `#[ApiResource]` attribute to your enum class:
+
+```php
+<?php
+// api/src/Enum/Status.php
+namespace App\Enum;
+
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource]
+enum Status: int
+{
+    case DRAFT = 0;
+    case PUBLISHED = 1;
+    case ARCHIVED = 2;
+}
+```
+
+By default, API Platform will automatically generate `GET` and `GET Collection` operations for your enum resource. The enum's `value` will be used as the identifier for individual enum cases.
+
+### Default Operations and Identifiers
+
+-   **Collection**: `GET /statuses` will return a collection of all enum cases.
+-   **Item**: `GET /statuses/{value}` will return a single enum case based on its `value`.
+
+Example `GET /statuses` response:
+
+```json
+[
+  {
+    "name": "DRAFT",
+    "value": 0
+  },
+  {
+    "name": "PUBLISHED",
+    "value": 1
+  },
+  {
+    "name": "ARCHIVED",
+    "value": 2
+  }
+]
+```
+
+Example `GET /statuses/1` response:
+
+```json
+{
+  "name": "PUBLISHED",
+  "value": 1
+}
+```
+
+### Customizing Enum Resources
+
+You can customize the behavior of enum resources using standard API Platform attributes.
+
+#### Custom Identifier
+
+If you wish to use a property other than `value` as the identifier, or to expose additional data, you can implement methods within your enum and mark them with `#[ApiProperty]`. For instance, to use the enum `name` as an identifier, you can implement `getId()`:
+
+```php
+<?php
+// api/src/Enum/Audit.php
+namespace App\Enum;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource]
+enum Audit: string
+{
+    case Pending = 'pending';
+    case Passed = 'passed';
+    case Failed = 'failed';
+
+    #[ApiProperty(identifier: true)]
+    public function getId(): string
+    {
+        return $this->name;
+    }
+}
+```
+#### Adding Custom Properties
+
+You can add custom properties to your enum resource by defining public methods and marking them with `#[ApiProperty]`:
+
+```php
+<?php
+// api/src/Enum/Status.php
+namespace App\Enum;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource]
+enum Status: int
+{
+    case DRAFT = 0;
+    case PUBLISHED = 1;
+    case ARCHIVED = 2;
+
+    #[ApiProperty]
+    public function getDescription(): string
+    {
+        return match ($this) {
+            self::DRAFT => 'Article is not ready for public consumption',
+            self::PUBLISHED => 'Article is publicly available',
+            self::ARCHIVED => 'Article content is outdated or superseded',
+        };
+    }
+}
+```
+
+With the above, `GET /statuses/0` might return:
+
+```json
+{
+  "name": "DRAFT",
+  "value": 0,
+  "description": "Article is not ready for public consumption"
+}
+```
+
+#### Custom State Providers
+
+For more advanced customization, you can implement custom state providers for your enum resources.
+A common pattern is to use a trait to provide common functionality:
+
+```php
+<?php
+// api/src/Enum/EnumApiResourceTrait.php
+namespace App\Enum;
+
+use ApiPlatform\Metadata\Operation;
+use BackedEnum;
+
+trait EnumApiResourceTrait
+{
+    public function getId(): string|int
+    {
+        return $this->value;
+    }
+
+    public function getValue(): int|string
+    {
+        return $this->value;
+    }
+
+    public static function getCases(): array
+    {
+        return self::cases();
+    }
+
+    public static function getCase(Operation $operation, array $uriVariables): ?BackedEnum
+    {
+        $id = is_numeric($uriVariables['id']) ? (int) $uriVariables['id'] : $uriVariables['id'];
+
+        return array_reduce(self::cases(), static fn($c, BackedEnum $case) => $case->name === $id || $case->value === $id ? $case : $c, null);
+    }
+}
+```
+
+Then, apply the trait and specify the providers in your enum:
+
+```php
+<?php
+// api/src/Enum/Audit.php
+namespace App\Enum;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+
+#[ApiResource]
+#[GetCollection(provider: Audit::class.'::getCases')]
+#[Get(provider: Audit::class.'::getCase')]
+enum Audit: string
+{
+    use EnumApiResourceTrait;
+
+    case Pending = 'pending';
+    case Passed = 'passed';
+    case Failed = 'failed';
+}
+```
+
+### Enums as Property Values
+
+When an enum is used as a property in another `ApiResource`, it will be serialized by its `value` by default.
+
+Consider an `Article` resource with a `Status` enum property:
+
+```php
+<?php
+// api/src/ApiResource/Article.php
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use App\Enum\Status; // Import your enum
+
+#[ApiResource]
+class Article
+{
+    public ?int $id = null;
+    public ?string $title = null;
+    public ?Status $status = null; // Enum property
+}
+```
+
+The serialization of `Article` will include the `value` of the `Status` enum:
+
+```json
+{
+  "id": 1,
+  "title": "Once Upon A Title",
+  "status": 1
+}
+```
+
+The OpenAPI schema will also correctly represent the enum as its backing type (`integer` for `Status`):
+
+```json
+{
+    "Article": {
+        "type": "object",
+        "properties": {
+            "id": {
+                "readOnly": true,
+                "type": "integer"
+            },
+            "title": {
+                "type": "string"
+            },
+            "status": {
+                "type": "integer",
+                "enum": [0, 1, 2] // Enum values derived from the BackedEnum
+            }
+        }
+    }
+}
+```
+
+### Referencing Enum Resources as Property Values
+
+If you have exposed an enum as an `ApiResource` (e.g., `#[ApiResource]` on `Status` enum), and then use that enum as a property in another resource (e.g., `Article::$status`), API Platform will serialize it as an IRI (Internationalized Resource Identifier) by default.
+
+```php
+<?php
+// api/src/ApiResource/Article.php
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use App\Enum\Status; // Assume Status is also an ApiResource
+
+#[ApiResource]
+class Article
+{
+    public ?int $id = null;
+    public ?string $title = null;
+    public ?Status $status = null; // This will now be an IRI
+}
+```
+
+The serialization of `Article` will include an IRI for the `Status` enum:
+
+```json
+{
+  "id": 1,
+  "title": "Once Upon A Title",
+  "status": "/statuses/1"
+}
+```
+
+If you prefer the enum to be serialized by its `value` instead of an IRI, even when it's an `ApiResource`, you might need to adjust your serialization context or create a custom normalizer if the default behavior doesn't suit your needs.

core/openapi.md

@@ -345,6 +345,7 @@ This will produce the following Swagger documentation:
 ```
 
 To pass a context to the OpenAPI **v2** generator, use the `swaggerContext` attribute (notice the prefix: `swagger` instead of `openapi`).
+For documentation on how to expose PHP 8.1+ Enums as API resources, refer to the [Enums documentation](enums.md).
 
 ## Disabling an Operation From OpenAPI Documentation
 

core/serialization.md

@@ -1,5 +1,7 @@
 # The Serialization Process
 
+For documentation on how to expose PHP 8.1+ Enums as API resources, refer to the [Enums documentation](enums.md).
+
 ## Overall Process
 
 API Platform embraces and extends the Symfony Serializer Component to transform PHP entities in (hypermedia) API responses.