Merge branch '4.0'

Author: dunglas

admin/getting-started.md

@@ -2,7 +2,7 @@
 
 ## Installation
 
-If you use the [API Platform Distribution](../distribution/), API Platform Admin is already installed, you can skip this installation guide.
+If you use the [API Platform Symfony variant](../symfony/), API Platform Admin is already installed, you can skip this installation guide.
 
 Otherwise, follow this guide.
 
@@ -37,7 +37,7 @@ export default () => (
 Be sure to make your API send proper [CORS HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to allow
 the admin's domain to access it.
 
-To do so, if you use the API Platform Distribution, update the value of the `CORS_ALLOW_ORIGIN` parameter in `api/.env` (it will be set to `^https?://localhost:?[0-9]*$`
+To do so, if you use the API Platform Symfony variant, update the value of the `CORS_ALLOW_ORIGIN` parameter in `api/.env` (it will be set to `^https?://localhost:?[0-9]*$`
 by default).
 
 If you use a custom installation of Symfony and [API Platform Core](../core/), you will need to adjust the [NelmioCorsBundle configuration](https://github.com/nelmio/NelmioCorsBundle#configuration) to expose the `Link` HTTP header and to send proper CORS headers on the route under which the API will be served (`/api` by default).

admin/index.md

@@ -17,7 +17,7 @@ library to expose a nice, responsive, management interface (Create-Retrieve-Upda
 
 You can **customize everything** by using provided React Admin and [MUI](https://mui.com/) components, or by writing your custom [React](https://reactjs.org/) components.
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/react-admin?cid=apip"><img src="../distribution/images/symfonycasts-player.png" alt="React Admin Screencast"><br>Watch the React Admin screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/react-admin?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="React Admin Screencast"><br>Watch the React Admin screencast</a></p>
 
 ## Features
 

core/content-negotiation.md

@@ -9,7 +9,7 @@ Using the raw JSON or raw XML formats is discouraged, prefer using JSON-LD inste
 
 API Platform also supports [JSON Merge Patch (RFC 7396)](https://tools.ietf.org/html/rfc7396) the JSON:API [`PATCH`](https://jsonapi.org/format/#crud-updating) formats, as well as [Problem Details (RFC 7807)](https://tools.ietf.org/html/rfc7807), [Hydra](https://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors) and [JSON:API](https://jsonapi.org/format/#errors) error formats.
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/formats?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="Formats screencast"><br>Watch the Formats screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/formats?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Formats screencast"><br>Watch the Formats screencast</a></p>
 
 API Platform will automatically detect the best resolving format depending on:
 

core/design.md

@@ -5,7 +5,7 @@ API framework. However, the "design-first" methodology is strongly recommended:
 API endpoints.
 
 To do so, you have to write a plain old PHP object (POPO) representing the input and output of your endpoint. This is the class
-that is [marked with the `#[ApiResource]` attribute](../distribution/index.md).
+that is [marked with the `#[ApiResource]` attribute](../symfony/index.md).
 This class **doesn't have** to be mapped with Doctrine ORM, or any other persistence system. It must be simple (it's usually
 just a data structure with no or minimal behaviors) and will be automatically converted to [Hydra](extending-jsonld-context.md),
 [OpenAPI](openapi.md) and [GraphQL](graphql.md) documentations or schemas by API Platform (there is a 1-1 mapping

core/extending-jsonld-context.md

@@ -2,7 +2,7 @@
 
 ## JSON-LD
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/json-ld?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="JSON-LD screencast"><br>Watch the JSON-LD screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/json-ld?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="JSON-LD screencast"><br>Watch the JSON-LD screencast</a></p>
 
 API Platform provides the possibility to extend the JSON-LD context of properties. This allows you to describe JSON-LD-typed
 values, inverse properties using the `@reverse` keyword and you can even overwrite the `@id` property this way. Everything you define
@@ -63,7 +63,7 @@ Note that you do not have to provide the `@id` attribute. If you do not provide
 
 ## Hydra
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/hydra?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="Hydra screencast"><br>Watch the Hydra screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/hydra?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Hydra screencast"><br>Watch the Hydra screencast</a></p>
 
 It's also possible to replace the Hydra context used by the documentation generator:
 

core/extending.md

@@ -35,4 +35,4 @@ For instance, if you want to send a mail after a resource has been persisted, bu
 
 To replace existing API Platform services with your decorators, [check out how to decorate services](https://symfony.com/doc/current/service_container/service_decoration.html).
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform-security/service-decoration?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="Service Decoration screencast"><br>Watch the Service Decoration screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform-security/service-decoration?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Service Decoration screencast"><br>Watch the Service Decoration screencast</a></p>

core/filters.md

@@ -12,7 +12,7 @@ By default, all filters are disabled. They must be enabled explicitly.
 When a filter is enabled, it automatically appears in the [OpenAPI](openapi.md) and [GraphQL](graphql.md) documentations.
 It is also automatically documented as a `hydra:search` property for JSON-LD responses.
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/filters?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="Filtering and Searching screencast"><br>Watch the Filtering & Searching screencast</a></p>
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/filters?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Filtering and Searching screencast"><br>Watch the Filtering & Searching screencast</a></p>
 
 ## Parameters
 

core/getting-started.md

@@ -1,42 +1,65 @@
 # Getting started
 
-## Migrating from FOSRestBundle
+## Installing API Platform
 
-If you plan to migrate from FOSRestBundle, you might want to read [this guide](migrate-from-fosrestbundle.md) to get started with API Platform.
+You can choose your preferred stack between Symfony, Laravel, or bootstrapping the API Platform core library manually.
 
-## Installing API Platform
+> [!CAUTION]
+>
+> If you are migrating from an older version of API Platform, make sure you read the [Upgrade Guide](upgrade-guide.md).
+
+### Symfony
+
+If you are starting a new project, the easiest way to get API Platform up is to install [API Platform for Symfony](../symfony/index.md).
 
-If you are starting a new project, the easiest way to get API Platform up is to install the [API Platform Distribution](../distribution/index.md).
 It comes with the API Platform core library integrated with [the Symfony framework](https://symfony.com), [the schema generator](../schema-generator/),
-[Doctrine ORM](https://www.doctrine-project.org), [Elasticsearch-PHP](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/index.html),
-[NelmioCorsBundle](https://github.com/nelmio/NelmioCorsBundle) and [Behat](https://behat.org/).
-[Doctrine MongoDB ODM](https://www.doctrine-project.org/projects/mongodb-odm.html) can also be enabled by following the [MongoDB documentation](mongodb.md).
-Basically, it is a Symfony edition packaged with the best tools to develop a REST API and sensible default settings.
+[Doctrine ORM](https://www.doctrine-project.org),
+[NelmioCorsBundle](https://github.com/nelmio/NelmioCorsBundle) and [test assertions dedicated to APIs](testing.md).
+
+[MongoDB](mongodb.md) and [Elasticsearch](elasticsearch.md) can also be easily enabled.
+
+Basically, it is a Symfony edition packaged with the best tools to develop a REST and GraphQL APIs and sensible default settings.
 
 Alternatively, you can use [Composer](https://getcomposer.org/) to install the standalone bundle in an existing Symfony Flex
 project:
 
-`composer require api`
+```console
+composer require API
+```
 
 There are no mandatory configuration options although [many settings are available](configuration.md).
 
-**Warning**: If you are migrating from an older version of API Platform than 2.7, make sure you read the [Upgrade Guide](upgrade-guide.md).
+### Migrating from FOSRestBundle
+
+If you plan to migrate from FOSRestBundle, you might want to read [this guide](migrate-from-fosrestbundle.md) to get started with API Platform.
+
+### Laravel
+
+API Platform can be installed on any new or existing Laravel project using [API Platform for Laravel](../laravel/index.md).
+
+It comes with integrations from the Laravel ecosystem, including [Eloquent](https://laravel.com/docs/eloquent), [Validation](https://laravel.com/docs/validation), [Authorization](https://laravel.com/docs/authorization), [Octane](https://laravel.com/docs/octane), [Pest](https://pestphp.com)...
+
+### Bootstrapping the Core Library
+
+While more complex, the core library [can also be installed in vanilla PHP projects and other frameworks](../core/bootstrap.md).
 
 ## Before Reading this Documentation
 
-If you haven't read it already, take a look at [the Getting Started guide](../distribution/index.md).
-This tutorial covers basic concepts required to understand how API Platform works including how it implements the REST pattern
+If you haven't read it already, take a look at [the Laravel Getting Started guide](../laravel/index.md) or [the Symfony Getting Started guide](../symfony/index.md).
+These tutorials cover basic concepts required to understand how API Platform works including how it implements the REST architectural style
 and what [JSON-LD](https://json-ld.org/) and [Hydra](https://www.hydra-cg.com/) formats are.
 
 ## Mapping the Entities
 
-<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/api-resource?cid=apip"><img src="/docs/distribution/images/symfonycasts-player.png" alt="Create an API Resource screencast"><br>Watch the Create an API Resource screencast</a></p>
+### Symfony with Doctrine
 
-API Platform is able to automatically expose entities mapped as "API resources" through a REST API supporting CRUD
+<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/api-resource?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Create an API Resource screencast"><br>Watch the Create an API Resource screencast</a></p>
+
+API Platform can automatically expose entities mapped as "API resources" through a REST API supporting CRUD
 operations.
-To expose your entities, you can use attributes, XML and YAML configuration files.
+To expose your entities, you can use attributes, XML, and YAML configuration files.
 
-Here is an example of entities mapped using attributes which will be exposed through a REST API:
+Here is an example of entities mapped using attributes that will be exposed through a REST API:
 
 ```php
 <?php
@@ -149,17 +172,20 @@ them unless you know what you are doing.
 Thanks to the mapping done previously, API Platform will automatically register the following REST [operations](operations.md)
 for resources of the product type:
 
-### Product
+### Product API using Symfony
 
 Method | URL            | Description
 -------|----------------|--------------------------------
 GET    | /products      | Retrieve the (paginated) collection
 POST   | /products      | Create a new product
 GET    | /products/{id} | Retrieve a product
-PUT    | /products/{id} | Update a product
 PATCH  | /products/{id} | Apply a partial modification to a product
 DELETE | /products/{id} | Delete a product
 
+> [!NOTE]
+>
+> `PUT` (replace or create) isn't registered automatically,
+> but is entirely supported by API Platform and can be added explicitly.
 The same operations are available for the offer method (routes will start with the `/offers` pattern).
 Route prefixes are built by pluralizing the name of the mapped entity class.
 It is also possible to override the naming convention using [operation path namings](operation-path-naming.md).
@@ -178,7 +204,6 @@ resources:
         types: ['https://schema.org/Offer']   # optional
         paginationItemsPerPage: 25           # optional
 ```
-
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
 <!-- api/config/api_platform/resources.xml -->
@@ -212,14 +237,107 @@ api_platform:
             - '%kernel.project_dir%/src/Entity' # default configuration for attributes
             - '%kernel.project_dir%/config/api_platform' # yaml or xml directory configuration
 ```
-
 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 [Symfony Local Web Server](https://symfony.com/doc/current/setup/symfony_server.html) (`symfony server:start`) and browse the API entrypoint at `http://localhost:8000/api`.
 
-Interact with the API using a REST client (we recommend [Postman](https://www.postman.com/)) or an Hydra-aware application
-(you should give [Hydra Console](https://github.com/lanthaler/HydraConsole) a try). Take
-a look at the usage examples in [the `features` directory](https://github.com/api-platform/core/tree/main/features).
+### Laravel with Eloquent
+
+API Platform introspects the database (column names, types, constraints, types, constraints...) to populate API Platform metadata.
+Serialization, OpenAPI, and hydra docs are generated from these metadata directly.
+
+#### Example
+
+First, create a migration class for the `products` table:
+
+```console
+ php artisan make:migration create_products_table
+```
+
+Open the generated migration class (`database/migrations/<timestamp>_create_products_table.php`) and add some columns:
+
+```patch
+    public function up(): void
+    {
+        Schema::create('products', function (Blueprint $table) {
+            $table->id();
+
++            $table->string('name');
++            $table->decimal('price', 8, 2);
++            $table->text('description');
++            $table->boolean('is_active')->default(true);
++            $table->date('created_date')->nullable();
+
+            $table->timestamps();
+        });
+    }
+```
+
+Finally, execute the migration:
+
+```console
+php artisan
+```
+
+And after that, just adding the `#[ApiResource]` attribute as follows onto your model:
+
+```patch
+<?php
+
+namespace App\Models;
+//app/Models/Product.php
++use ApiPlatform\Metadata\ApiResource;
+use Illuminate\Database\Eloquent\Model;
+ 
++#[ApiResource]
+class Product extends Model {}
+```
+
+While attributes (introduced in PHP 8) are the preferred way to configure your API Platform resources, it’s also possible to use a trait instead.
+```patch
+<?php
+
+namespace App\Models;
+//app/Models/Product.php
++use ApiPlatform\Metadata\IsApiResource;
+use Illuminate\Database\Eloquent\Model;
+ 
+class Product extends Model 
+{
++   use IsApiResource;
+}
+```
+
+See the [Using The IsApiResourceTrait Instead of Attributes documentation](../laravel/index.md#using-the-isapiresourcetrait-instead-of-attributes) for examples of advanced configuration in both cases (attributes or static method).
+
+**You're done!** 🎉
+
+You now have a fully featured API exposing your entities.
+
+Run the Laravel app with the Laravel's local development server using [the Artisan Console component](https://laravel.com/docs/artisan) (`php artisan serve`) and browse the API entrypoint at `http://localhost:8000/api`.
+
+Using configurations, API Platform generates metadata that will automatically register the following REST [operations](operations.md)
+for resources of the product type:
+
+### Product API using Laravel
+
+Method | URL            | Description
+-------|----------------|--------------------------------
+GET    | /products      | Retrieve the (paginated) collection
+POST   | /products      | Create a new product
+GET    | /products/{id} | Retrieve a product
+PATCH  | /products/{id} | Apply a partial modification to a product
+DELETE | /products/{id} | Delete a product
+
+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)
+
+## Interactions with the API
+
+Interact with the API using a REST client (we recommend [Hoppscotch](https://hoppscotch.io/)) or [API Platform Admin](../admin/index.md).
+
+## Examples
+
+Take a look at [the API Platform demo](https://github.com/api-platform/demo).

core/graphql.md

@@ -21,7 +21,7 @@ docker compose exec php sh -c '
 
 You can now use GraphQL at the endpoint: `https://localhost:8443/graphql`.
 
-*Note:* If you used [Symfony Flex to install API Platform](../distribution/index.md#using-symfony-flex-and-composer-advanced-users), URLs will be prefixed with `/api` by default. For example, the GraphQL endpoint will be: `https://localhost:8443/api/graphql`.
+*Note:* If you used [Symfony Flex to install API Platform](../symfony/index.md#using-symfony-flex-and-composer-advanced-users), URLs will be prefixed with `/api` by default. For example, the GraphQL endpoint will be: `https://localhost:8443/api/graphql`.
 
 ## Changing Location of the GraphQL Endpoint