From 375cb505c0420186803daf03435be96175926476 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Sun, 8 Mar 2026 22:09:55 +0100 Subject: [PATCH 1/3] Add documentation for PHP file resource configuration format --- core/configuration.md | 3 +++ core/getting-started.md | 46 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/core/configuration.md b/core/configuration.md index 51e08d033df..2277300b259 100644 --- a/core/configuration.md +++ b/core/configuration.md @@ -95,6 +95,9 @@ api_platform: partial_parameter_name: 'partial' mapping: + # The list of directories containing PHP files that return ApiResource instances. + imports: [] + # The list of paths with files or directories where the bundle will look for additional resource files. paths: [] diff --git a/core/getting-started.md b/core/getting-started.md index b0034f0b68e..4eeb9942d69 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -203,10 +203,44 @@ Thanks to the mapping done previously, API Platform will automatically register > of the mapped entity class. It is also possible to override the naming convention using > [operation path namings](operation-path-naming.md). -As an alternative to attributes, you can map entity classes using YAML or XML: +As an alternative to attributes, you can map entity classes using PHP, YAML or XML files: +```php +withClass(Product::class); +``` + +```php +withClass(Offer::class) + ->withShortName('Offer') + ->withDescription('An offer from my shop') + ->withTypes(['https://schema.org/Offer']) + ->withPaginationItemsPerPage(25) + ->withOperations(new Operations([ + new Get(), + new GetCollection(), + new Post(), + ])); +``` + ```yaml # api/config/api_platform/resources.yaml resources: @@ -241,7 +275,7 @@ resources: -If you prefer to use YAML or XML files instead of attributes, you must configure API Platform to +If you prefer to use YAML, XML or PHP files instead of attributes, you must configure API Platform to load the appropriate files: ```yaml @@ -251,8 +285,16 @@ api_platform: paths: - "%kernel.project_dir%/src/Entity" # default configuration for attributes - "%kernel.project_dir%/config/api_platform" # yaml or xml directory configuration + imports: + - "%kernel.project_dir%/config/api_platform/resources" # php directory configuration ``` +> [!NOTE] +> +> PHP resource files must be placed in a directory listed under `mapping.imports` (not `mapping.paths`). +> Each file must return an `ApiResource` instance. Since these files are not autoloaded, they won't +> conflict with your entity classes. This approach provides the same fluent API as PHP attributes. + If you want to serialize only a subset of your data, please refer to the [Serialization documentation](serialization.md). **You're done!** You now have a fully featured API exposing your entities. Run the Symfony app with the From 58891aaa0eb403d800f9fd446756f750dbcad1eb Mon Sep 17 00:00:00 2001 From: lacatoire Date: Sun, 8 Mar 2026 22:13:03 +0100 Subject: [PATCH 2/3] Fix Prettier formatting on getting-started.md --- core/getting-started.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/core/getting-started.md b/core/getting-started.md index 4eeb9942d69..4f73f023ccc 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -275,8 +275,8 @@ resources: -If you prefer to use YAML, XML or PHP files instead of attributes, you must configure API Platform to -load the appropriate files: +If you prefer to use YAML, XML or PHP files instead of attributes, you must configure API Platform +to load the appropriate files: ```yaml # api/config/packages/api_platform.yaml @@ -291,9 +291,10 @@ api_platform: > [!NOTE] > -> PHP resource files must be placed in a directory listed under `mapping.imports` (not `mapping.paths`). -> Each file must return an `ApiResource` instance. Since these files are not autoloaded, they won't -> conflict with your entity classes. This approach provides the same fluent API as PHP attributes. +> PHP resource files must be placed in a directory listed under `mapping.imports` (not +> `mapping.paths`). Each file must return an `ApiResource` instance. Since these files are not +> autoloaded, they won't conflict with your entity classes. This approach provides the same fluent +> API as PHP attributes. If you want to serialize only a subset of your data, please refer to the [Serialization documentation](serialization.md). **You're done!** You now have a fully featured API @@ -399,12 +400,12 @@ REST [operations](operations.md) for resources of the product type: In addition, among other things, API Platform under the hood does the following: -- Generated machine-readable documentations of the API in the - [OpenAPI (formerly known as Swagger)](../core/openapi.md) (available at - `http://127.0.0.1:8000/api/docs.json`) and - [JSON-LD](https://json-ld.org)/[Hydra](https://www.hydra-cg.com) formats using this metadata -- Generated nice human-readable documentation and a sandbox for the API with - [SwaggerUI](https://swagger.io/tools/swagger-ui/) (Redoc is also available out-of-the-box) +- Generated machine-readable documentations of the API in the + [OpenAPI (formerly known as Swagger)](../core/openapi.md) (available at + `http://127.0.0.1:8000/api/docs.json`) and + [JSON-LD](https://json-ld.org)/[Hydra](https://www.hydra-cg.com) formats using this metadata +- Generated nice human-readable documentation and a sandbox for the API with + [SwaggerUI](https://swagger.io/tools/swagger-ui/) (Redoc is also available out-of-the-box) ## Interactions with the API From 5aab8638dba32c2c69d16cbaba706d55b54a920b Mon Sep 17 00:00:00 2001 From: lacatoire Date: Sun, 8 Mar 2026 22:17:57 +0100 Subject: [PATCH 3/3] Fix formatting: use Prettier 3.8.1 to match CI --- core/getting-started.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/core/getting-started.md b/core/getting-started.md index 4f73f023ccc..8ba64c8a18b 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -400,12 +400,12 @@ REST [operations](operations.md) for resources of the product type: In addition, among other things, API Platform under the hood does the following: -- Generated machine-readable documentations of the API in the - [OpenAPI (formerly known as Swagger)](../core/openapi.md) (available at - `http://127.0.0.1:8000/api/docs.json`) and - [JSON-LD](https://json-ld.org)/[Hydra](https://www.hydra-cg.com) formats using this metadata -- Generated nice human-readable documentation and a sandbox for the API with - [SwaggerUI](https://swagger.io/tools/swagger-ui/) (Redoc is also available out-of-the-box) +- Generated machine-readable documentations of the API in the + [OpenAPI (formerly known as Swagger)](../core/openapi.md) (available at + `http://127.0.0.1:8000/api/docs.json`) and + [JSON-LD](https://json-ld.org)/[Hydra](https://www.hydra-cg.com) formats using this metadata +- Generated nice human-readable documentation and a sandbox for the API with + [SwaggerUI](https://swagger.io/tools/swagger-ui/) (Redoc is also available out-of-the-box) ## Interactions with the API