From bed10f577522218e4f6a5aeebffc83a812b949b3 Mon Sep 17 00:00:00 2001 From: soyuka Date: Fri, 12 Jun 2026 09:47:19 +0200 Subject: [PATCH] docs: align getting-started with the api-platform CLI installer The api-platform/api-platform repository becomes a CLI installer that scaffolds projects, replacing the downloadable distribution archive (the bundled Docker app, the PWA skeleton and the Helm chart). - symfony/index.md: rewrite the install section around the `api-platform` binary. Update the services/components tables (the Next.js PWA now runs as a standalone app, the admin as a separate SPA), the demo resource (Greetings ApiResource), and repoint template-sync to dunglas/symfony-docker - laravel/index.md: add the CLI installer as the recommended entry point, keep the manual composer/artisan flow for existing projects - deployment/kubernetes.md, minikube.md, *testing.md: the Helm chart is no longer bundled; point to the chart preserved at the v4.1 tag - core/*, symfony/*, create-client/*, schema-generator/*, laravel/*: replace stale "the distribution" wording with "the API Platform Symfony variant" / "the Docker setup"; repoint dead installer-repo CI links to api-platform/demo --- core/errors.md | 4 +- core/events.md | 6 +- core/filters.md | 2 +- core/mercure.md | 4 +- core/mongodb.md | 4 +- core/performance.md | 12 +- core/push-relations.md | 6 +- core/serialization.md | 6 +- create-client/nextjs.md | 4 +- deployment/kubernetes.md | 13 ++- deployment/minikube.md | 3 +- laravel/filters.md | 4 +- laravel/index.md | 30 +++++ laravel/testing.md | 10 +- schema-generator/getting-started.md | 4 +- symfony/caddy.md | 2 +- symfony/controllers.md | 4 +- symfony/debugging.md | 3 +- symfony/index.md | 172 ++++++++++++++++------------ symfony/jwt.md | 10 +- symfony/testing.md | 16 ++- 21 files changed, 193 insertions(+), 126 deletions(-) diff --git a/core/errors.md b/core/errors.md index 2660dcd5d4f..a31c22173cc 100644 --- a/core/errors.md +++ b/core/errors.md @@ -116,8 +116,8 @@ final class ProductManager implements EventSubscriberInterface } ``` -If you use the standard distribution of API Platform, this event listener will be automatically -registered. If you use a custom installation, [learn how to extend API Platform](extending.md). +If you use the API Platform Symfony variant, this event listener will be automatically registered. +If you use a custom installation, [learn how to extend API Platform](extending.md). Then, configure the framework to catch `App\Exception\ProductNotFoundException` exceptions and convert them into `404` errors: diff --git a/core/events.md b/core/events.md index a9ae9396796..e6f8c7dc19d 100644 --- a/core/events.md +++ b/core/events.md @@ -142,9 +142,9 @@ final class BookMailSubscriber implements EventSubscriberInterface } ``` -If you use the official API Platform distribution, creating the previous class is enough. The -Symfony DependencyInjection component will automatically register this subscriber as a service and -will inject its dependencies thanks to the +If you use the API Platform Symfony variant, creating the previous class is enough. The Symfony +DependencyInjection component will automatically register this subscriber as a service and will +inject its dependencies thanks to the [autowiring feature](https://symfony.com/doc/current/service_container/autowiring.html). Alternatively, diff --git a/core/filters.md b/core/filters.md index 9f75a6881d9..bda05008e4d 100644 --- a/core/filters.md +++ b/core/filters.md @@ -599,7 +599,7 @@ because `bar` is not a supported parameter. > [!NOTE] We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this filter. > Vulcain is faster, allows a better hit rate, and is supported out of the box in the API Platform -> distribution. [!NOTE] When unsing JSON:API check out the +> Symfony variant. [!NOTE] When unsing JSON:API check out the > [specific SparseFieldset and Sort filters](./content-negotiation/#jsonapi-sparse-fieldset-and-sort-parameters) The property filter adds the possibility to select the properties to serialize (sparse fieldsets). diff --git a/core/mercure.md b/core/mercure.md index 7cea94354e5..2f8493ace4e 100644 --- a/core/mercure.md +++ b/core/mercure.md @@ -19,8 +19,8 @@ Mercure hub. Then, the Mercure hub dispatches the updates to all connected clien ## Installing Mercure Support Mercure support is already installed, configured and enabled in -[the API Platform Symfony variant](../symfony/index.md). If you use the distribution, you have -nothing more to do, and you can skip to the next section. +[the API Platform Symfony variant](../symfony/index.md). If you use it, you have nothing more to do, +and you can skip to the next section. If you installed API Platform using another method (e.g., `composer require api`), you will need to set up the following: diff --git a/core/mongodb.md b/core/mongodb.md index f6e48eed9f9..db56b3a4914 100644 --- a/core/mongodb.md +++ b/core/mongodb.md @@ -22,8 +22,8 @@ extension and not on the legacy [mongo](https://secure.php.net/manual/en/book.mo If the `mongodb` PHP extension is not installed yet, [install it beforehand](https://secure.php.net/manual/en/mongodb.installation.pecl.php). -Or if you are using the [API Platform Distribution with Symfony](../symfony/index.md), modify the -`Dockerfile` to add the extension: +Or if you are using the [API Platform Symfony variant](../symfony/index.md) with Docker, modify the +`api/Dockerfile` to add the extension: ```diff # api/Dockerfile diff --git a/core/performance.md b/core/performance.md index 2b40a4933d4..ea3808271fd 100644 --- a/core/performance.md +++ b/core/performance.md @@ -27,8 +27,8 @@ document is added or removed or for relationships and inverse relations is built #### Built-in Caddy HTTP Cache -The API Platform distribution relies on the [Caddy web server](https://caddyserver.com) which -provides an official HTTP cache module called +The Docker setup of the API Platform Symfony variant relies on the +[Caddy web server](https://caddyserver.com) which provides an official HTTP cache module called [cache-handler](https://github.com/caddyserver/cache-handler), that is based on [Souin](https://github.com/darkweak/souin). @@ -332,18 +332,18 @@ class Book Computing metadata used by the bundle is a costly operation. Fortunately, metadata can be computed once and then cached. API Platform internally uses a [PSR-6](https://www.php-fig.org/psr/psr-6/) -cache. If the Symfony Cache component is available (the default in the API Platform distribution), -it automatically enables support for the best cache adapter available. +cache. If the Symfony Cache component is available (the default in the API Platform Symfony +variant), it automatically enables support for the best cache adapter available. Best performance is achieved using [APCu](https://github.com/krakjoe/apcu). Be sure to have the APCu extension installed on your production server (this is the case by default in the Docker image -provided by the API Platform distribution). API Platform will automatically use it. +provided by the API Platform Symfony variant). API Platform will automatically use it. ## Using FrankenPHP's Worker Mode API response times can be significantly improved by enabling [FrankenPHP's worker mode](https://frankenphp.dev/docs/worker/). This feature is enabled by default -in the production environment of the API Platform distribution. +in the production environment of the API Platform Symfony variant. ## Doctrine Queries and Index diff --git a/core/push-relations.md b/core/push-relations.md index d91a8a1a606..1c7e9416941 100644 --- a/core/push-relations.md +++ b/core/push-relations.md @@ -11,7 +11,7 @@ API Platform leverages this capability by pushing relations of a resource to cli > [!NOTE] We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this feature. > Vulcain is faster, cleaner, more flexible, and is supported out of the box in -> [the API Platform distribution](../symfony/index.md). +> [the API Platform Symfony variant](../symfony/index.md). ```php [!NOTE] If you are not using the API Platform distribution, you need to enable annotation support -> in the serializer configuration as outlined below, depending on your Symfony version. +> [!NOTE] If you are not using the API Platform Symfony variant, you need to enable annotation +> support in the serializer configuration as outlined below, depending on your Symfony version. #### Configuration for Symfony `<= 6.4` @@ -401,7 +401,7 @@ requests. **Note:** We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this feature. Vulcain allows creating faster (better hit rate) and better designed APIs than relying on compound -documents, and is supported out of the box in the API Platform distribution. +documents, and is supported out of the box in the API Platform Symfony variant. ### Normalization diff --git a/create-client/nextjs.md b/create-client/nextjs.md index c0007a7d08a..aabb3d612e1 100644 --- a/create-client/nextjs.md +++ b/create-client/nextjs.md @@ -60,8 +60,8 @@ The generated HTML will contain [Tailwind CSS](https://tailwindcss.com) classes. ## Generating Routes -If you are using the [API Platform Distribution with Symfony](../symfony/index.md) generating all -the code you need for a given resource is as simple as running the following command: +If you are using the [API Platform Symfony variant](../symfony/index.md) generating all the code you +need for a given resource is as simple as running the following command: ```console docker compose exec pwa \ diff --git a/deployment/kubernetes.md b/deployment/kubernetes.md index 79decd69618..67704845c24 100644 --- a/deployment/kubernetes.md +++ b/deployment/kubernetes.md @@ -6,8 +6,17 @@ containers in production. [Google Cloud Platform](https://cloud.google.com/kuber [Amazon Web Services](https://aws.amazon.com/eks/) and many more companies provide managed Kubernetes environment. -[The API Platform symfony variant](../symfony/index.md) contains a built-in [Helm](https://helm.sh/) -(the k8s package manager) chart to deploy in a wink on any of these platforms. +API Platform can be deployed to any of these platforms with a [Helm](https://helm.sh/) (the k8s +package manager) chart. + +> [!NOTE] +> +> The Helm chart is no longer bundled with the project scaffolded by the `api-platform` installer. A +> reworked chart is in the works. In the meantime, you can use the chart preserved in the `4.1` +> release of the distribution: copy the +> [`helm/api-platform`](https://github.com/api-platform/api-platform/tree/v4.1.0/helm/api-platform) +> directory from that tag into your project, and adapt it to your image names and project layout. +> The commands below assume it is available at `./helm/api-platform`. This guide is based on Helm 3. diff --git a/deployment/minikube.md b/deployment/minikube.md index 8839396bc22..4f00a036b43 100644 --- a/deployment/minikube.md +++ b/deployment/minikube.md @@ -15,7 +15,8 @@ The previous command starts minikube with a Docker registry (we'll use it in the the Kubernetes dashboard. Finally, [install Helm](https://helm.sh/docs/intro/install/). We'll use it to deploy the application -in the cluster thanks to the chart provided in the API Platform distribution. +in the cluster thanks to a Helm chart (see the [Kubernetes guide](kubernetes.md) for how to obtain +it). ## Building and Pushing Docker Images diff --git a/laravel/filters.md b/laravel/filters.md index 09118b28d49..5c77192d74f 100644 --- a/laravel/filters.md +++ b/laravel/filters.md @@ -271,8 +271,8 @@ Examples: ### PropertyFilter Note: We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this filter. Vulcain -is faster, allows a better hit rate, and is supported out of the box in the API Platform -distribution. +is faster, allows a better hit rate, and is supported out of the box in the API Platform Symfony +variant. The property filter adds the possibility to select the properties to serialize (sparse fieldsets). diff --git a/laravel/index.md b/laravel/index.md index 3a3d2dd0db2..3a9b238010e 100644 --- a/laravel/index.md +++ b/laravel/index.md @@ -39,6 +39,36 @@ With API Platform, you can: Let's discover how to use API Platform with Laravel! +## Scaffolding a New Project (Recommended) + +The fastest way to start a new project is the **`api-platform` installer**, a command-line tool that +creates a ready-to-use Laravel project with API Platform pre-installed. + +Download the latest release for your platform from the +[Releases page](https://github.com/api-platform/api-platform/releases/latest) and move the binary +somewhere on your `$PATH`: + +```console +curl -L https://github.com/api-platform/api-platform/releases/latest/download/api-platform-linux-x86_64 -o /usr/local/bin/api-platform +chmod +x /usr/local/bin/api-platform +``` + +Alternatively, if you already have PHP and [Composer](https://getcomposer.org/) installed, install +it globally with `composer global require api-platform/installer`. + +Then scaffold the project: + +```console +api-platform my-api-platform-laravel-app --framework=laravel +``` + +The installer creates the Laravel application, requires `api-platform/laravel`, and runs +`php artisan api-platform:install` for you. Once it finishes, start the server with +`php artisan serve` and open `http://127.0.0.1:8000/api/`. + +If you prefer to install API Platform manually, or you want to add it to an existing Laravel +project, follow the sections below instead. + ## Installing Laravel API Platform can be installed easily on new and existing Laravel projects. If you already have an diff --git a/laravel/testing.md b/laravel/testing.md index 7d4f48dae19..5e6e3d45500 100644 --- a/laravel/testing.md +++ b/laravel/testing.md @@ -462,21 +462,19 @@ Running your test suite in your [CI/CD pipeline](https://en.wikipedia.org/wiki/Continuous_integration) is important to ensure good quality and delivery time. -The API Platform distribution is -[shipped with a GitHub Actions workflow](https://github.com/api-platform/api-platform/blob/main/.github/workflows/ci.yml) +The API Platform Demo is +[shipped with a GitHub Actions workflow](https://github.com/api-platform/demo/tree/main/.github/workflows) that builds the Docker images, does a [smoke test]() to check that the application's entrypoint is accessible, and runs PHPUnit. The API Platform Demo [contains a CD workflow](https://github.com/api-platform/demo/tree/main/.github/workflows) that uses -[the Helm chart provided with the distribution](../deployment/kubernetes.md) to deploy the app on a -Kubernetes cluster. +[a Helm chart](../deployment/kubernetes.md) to deploy the app on a Kubernetes cluster. ## Additional and Alternative Testing Tools -You may also be interested in these alternative testing tools (not included in the API Platform -distribution): +You may also be interested in these alternative testing tools (not included by default): - [Hoppscotch](https://docs.hoppscotch.io/features/tests), create functional test for your API - [Behat](https://behat.org), a diff --git a/schema-generator/getting-started.md b/schema-generator/getting-started.md index c5e5621af83..4b9e0e99d79 100644 --- a/schema-generator/getting-started.md +++ b/schema-generator/getting-started.md @@ -2,8 +2,8 @@ ## Installation -If you use [the API Platform Distribution with Symfony](../symfony/index.md), the Schema Generator -is already installed as a development dependency of your project and can be invoked with: +If you use [the API Platform Symfony variant](../symfony/index.md), the Schema Generator is already +installed as a development dependency of your project and can be invoked with: ```console vendor/bin/schema diff --git a/symfony/caddy.md b/symfony/caddy.md index 45498c5eab6..0c907a2cb0d 100644 --- a/symfony/caddy.md +++ b/symfony/caddy.md @@ -1,6 +1,6 @@ # Configuring the Caddy Web Server with Symfony -[The API Platform distribution](index.md) is shipped with +[The API Platform Symfony variant](index.md), when generated with Docker, is shipped with [the Caddy web server](https://caddyserver.com). The build contains the [Mercure](../core/mercure.md) and the [Vulcain](https://vulcain.rocks) Caddy modules. diff --git a/symfony/controllers.md b/symfony/controllers.md index 301ccc4937b..276179e12f1 100644 --- a/symfony/controllers.md +++ b/symfony/controllers.md @@ -30,7 +30,7 @@ Internally, API Platform implements the [Action-Domain-Responder](https://github pattern (ADR), a web-specific refinement of [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller). -The distribution of API Platform also eases the implementation of the ADR pattern: it automatically +The API Platform Symfony variant also eases the implementation of the ADR pattern: it automatically registers action classes stored in `api/src/Controller` as autowired services. Thanks to the [autowiring](https://symfony.com/doc/current/service_container/autowiring.html) @@ -85,7 +85,7 @@ corresponding to the ID passed in the URL. Here we consider that [autowiring](https://symfony.com/doc/current/service_container/autowiring.html) is enabled for -controller classes (the default when using the API Platform distribution). This action will be +controller classes (the default when using the API Platform Symfony variant). This action will be automatically registered as a service (the service name is the same as the class name: `App\Controller\CreateBookPublication`). diff --git a/symfony/debugging.md b/symfony/debugging.md index 9e8045d93d5..bbd55186573 100644 --- a/symfony/debugging.md +++ b/symfony/debugging.md @@ -5,7 +5,8 @@ ## Xdebug For development purposes such as debugging tests or remote API requests, -[Xdebug](https://xdebug.org/) is shipped by default with the API Platform distribution. +[Xdebug](https://xdebug.org/) is shipped by default with the Docker setup of the API Platform +Symfony variant. To enable it, run: diff --git a/symfony/index.md b/symfony/index.md index c9da5f39159..760c63f7479 100644 --- a/symfony/index.md +++ b/symfony/index.md @@ -25,26 +25,23 @@ API Platform is shipped with **[Docker](../deployment/docker-compose.md)** and **[Kubernetes](../deployment/kubernetes.md)** definitions, to develop and deploy instantly on the cloud. -The easiest and most powerful way to get started is -[to download the API Platform distribution](https://github.com/api-platform/api-platform/releases). -It contains: +The easiest and most powerful way to get started is to use the **`api-platform` installer**, a +command-line tool that scaffolds a new project for you. Depending on the options you select, it can +generate: - the API skeleton, including [the Core library](../core/index.md), [the Symfony framework](https://symfony.com/) ([optional](../core/bootstrap.md)) and [the Doctrine ORM](https://www.doctrine-project.org/projects/orm.html) ([optional](../core/extending.md)) -- [the client scaffolding tool](../create-client/index.md) to generate - [Next.js](../create-client/index.md) web applications from the API documentation - ([Nuxt](https://nuxt.com/), [Vue](https://vuejs.org/), [Create React App](https://reactjs.org), - [React Native](https://reactnative.dev/), [Quasar](https://quasar.dev/) and - [Vuetify](https://vuetifyjs.com/) are also supported) - [a beautiful admin interface](../admin/index.md), built on top of React Admin, dynamically created by parsing the API documentation +- a [Next.js](../create-client/nextjs.md) Progressive Web App, ready to welcome the code generated + by [the client scaffolding tool](../create-client/index.md) ([Nuxt](https://nuxt.com/), + [Vue](https://vuejs.org/), [React Native](https://reactnative.dev/), [Quasar](https://quasar.dev/) + and [Vuetify](https://vuetifyjs.com/) are also supported) - all you need to [create real-time and async APIs using the Mercure protocol](../core/mercure.md) - a [Docker](../deployment/docker-compose.md) definition to start a working development environment in a single command, providing containers for the API and the Next.js web application -- a [Helm](https://helm.sh/) chart to deploy the API in any - [Kubernetes](../deployment/kubernetes.md) cluster ## A Bookshop API @@ -75,7 +72,7 @@ features: - [invalidation-based HTTP caching](../core/performance.md) - and basically everything needed to build modern APIs. -One more thing, before we start: as the API Platform distribution includes +One more thing, before we start: as the generated project is built on top of [the Symfony framework](https://symfony.com), it is compatible with most [Symfony bundles](https://symfony.com/bundles) (plugins) and benefits from [the numerous extension points](../core/extending.md) provided by this rock-solid foundation @@ -85,18 +82,49 @@ is straightforward. ## Installing the Framework -### Using the API Platform Distribution (Recommended) +### Using the API Platform Installer (Recommended) -Start by -[downloading the API Platform distribution](https://github.com/api-platform/api-platform/releases/latest), -or -[generate a GitHub repository from the template we provide](https://github.com/new?template_name=api-platform&template_owner=api-platform). -You will add your own code and configuration inside this skeleton. +The `api-platform` installer is a command-line tool that scaffolds a new project for you. -**Note**: Avoid downloading the `.zip` archive, as it may cause potential -[permission](https://github.com/api-platform/api-platform/issues/319#issuecomment-307037562) -[issues](https://github.com/api-platform/api-platform/issues/777#issuecomment-412515342), prefer the -`.tar.gz` archive. +#### Installing the CLI + +Download the latest release for your platform from the +[Releases page](https://github.com/api-platform/api-platform/releases/latest) and move the binary +somewhere on your `$PATH`: + +```console +curl -L https://github.com/api-platform/api-platform/releases/latest/download/api-platform-linux-x86_64 -o /usr/local/bin/api-platform +chmod +x /usr/local/bin/api-platform +``` + +Alternatively, if you already have PHP and [Composer](https://getcomposer.org/) installed, you can +install the installer globally with Composer: + +```console +composer global require api-platform/installer +``` + +The `api-platform` binary will then be available in `~/.composer/vendor/bin` (make sure this +directory is in your `$PATH`). + +#### Scaffolding the Project + +This tutorial builds a full stack project (API, admin and a Next.js Progressive Web App), so we +generate it with the `--with-pwa` and `--with-admin` options. Run: + +```console +api-platform bookshop-api --framework=symfony --with-docker --with-pwa --with-admin +``` + +> [!TIP] +> +> Run `api-platform` without any argument to start the interactive wizard, which lets you pick the +> framework, the API formats, the documentation UI, and whether to include Docker, the admin and the +> PWA. + +When the PWA and the admin are enabled, the installer creates a project directory containing an +`api/` subdirectory (the Symfony API) alongside a `pwa/` directory (the Next.js application) and an +`admin/` directory (the React-admin SPA). The rest of this tutorial assumes this layout. API Platform is shipped with a [Docker](https://docker.com) definition that makes it easy to get a containerized development environment up and running. If you do not already have Docker on your @@ -106,18 +134,11 @@ computer, it's the right time to [install it](https://docs.docker.com/get-docker Similarly, on Windows, only [Docker for Windows](https://docs.docker.com/docker-for-windows/) is supported. Docker Machine **is not** supported out of the box. -Open a terminal, and navigate to the directory containing your project skeleton. Run the following -command to start all services using [Docker Compose](https://docs.docker.com/compose/): - -Build the images: - -```console -docker compose build --no-cache -``` - -Then, start Docker Compose in detached mode: +Open a terminal and navigate to the generated `api/` directory. Run the following command to start +all services using [Docker Compose](https://docs.docker.com/compose/): ```console +cd bookshop-api/api docker compose up --wait ``` @@ -142,16 +163,18 @@ This starts the following services: | Name | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | php | The API powered by [FrankenPHP](https://frankenphp.dev) (a modern application server for PHP built on top of [Caddy web server](caddy.md) and with native support for [Mercure realtime](../core/mercure.md), [Vulcain relations preloading](https://vulcain.rocks), and [XDebug](debugging.md)), Composer, and sensitive configs | -| pwa | Next.js project compatible with Create Client and having Admin preinstalled | | database | PostgreSQL database server | +When generated with `--with-pwa`, the Next.js application lives in the sibling `pwa/` directory. It +is **not** part of the Docker Compose stack: you run it separately with its own development server +(see [A Next.js Web App](#a-nextjs-web-app) below). + The following components are available: -| URL | Path | Language | Description | -| -------------------------- | ------------------ | ---------- | ----------------------- | -| `https://localhost/docs/` | `api/` | PHP | The API | -| `https://localhost/` | `pwa/` | TypeScript | The Next.js application | -| `https://localhost/admin/` | `pwa/pages/admin/` | TypeScript | The Admin | +| URL | Path | Language | Description | +| ------------------------- | ------ | ---------- | --------------------------------------------- | +| `https://localhost/docs/` | `api/` | PHP | The API | +| `http://localhost:3000/` | `pwa/` | TypeScript | The Next.js application (run with `pnpm dev`) | To see the container's logs, run: @@ -174,15 +197,15 @@ analysis. [PHP Intelephense for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client) also works well, and is free and open source. -The API Platform distribution comes with a dummy entity for test purposes: -`api/src/Entity/Greeting.php`. We will remove it later. +The installer creates a dummy API resource for test purposes: `api/src/ApiResource/Greetings.php`. +We will remove it later. -If you're used to the PHP ecosystem, you probably guessed that this test entity uses the -industry-leading [Doctrine ORM](https://www.doctrine-project.org/projects/orm.html) library as a -persistence system. It is shipped, in the API Platform distribution. +The installer also requires the [Doctrine ORM](https://www.doctrine-project.org/projects/orm.html) +bridge (`api-platform/doctrine-orm`), the industry-leading PHP persistence system, so you can start +mapping your own entities right away. -Doctrine ORM is the easiest way to persist and query data in an API Platform project thanks to the -bridge shipped with the distribution, but it's also entirely optional, and +Doctrine ORM is the easiest way to persist and query data in an API Platform project thanks to this +bridge, but it's also entirely optional, and [you may prefer to plug your own persistence system](../core/design.md). The Doctrine Bridge is optimized for performance and development convenience. For instance, when @@ -208,10 +231,10 @@ Alternatively, the API Platform server component can also be installed directly **This method is recommended only for users who want full control over the directory structure and the installed dependencies.** -[For a good introduction, watch how to install API Platform without the distribution on SymfonyCasts](https://symfonycasts.com/screencast/api-platform/install?cid=apip). +[For a good introduction, watch how to install API Platform manually on SymfonyCasts](https://symfonycasts.com/screencast/api-platform/install?cid=apip). -The rest of this tutorial assumes that you have installed API Platform using the official -distribution. Go straight to the next section if it's your case. +The rest of this tutorial assumes that you have scaffolded your project with the `api-platform` +installer. Go straight to the next section if it's your case. API Platform has an official Symfony Flex recipe. It means that you can easily install it from any Symfony application using [the Symfony binary](https://symfony.com/download): @@ -267,10 +290,9 @@ Open `https://localhost` in your favorite web browser: You'll need to add a security exception in your browser to accept the self-signed TLS certificate that has been generated for this container when installing the framework. -Later you will probably replace this welcome screen by the homepage of your Next.js application. If -you don't plan to create a Progressive Web App, you can remove the `pwa/` directory as well as the -related lines in `docker-compose*.yml` and in `api/frankenphp/Caddyfile` (don't do it now, we'll use -this container later in this tutorial). +If you generated the project without `--with-pwa`, you can skip this welcome screen and build your +Next.js application separately later. When the PWA is included, it runs as a standalone Next.js app +in the sibling `pwa/` directory (don't remove it now, we'll use it later in this tutorial). Click on the "API" button, or go to `https://localhost/docs/`: @@ -280,12 +302,12 @@ API Platform exposes a description of the API in the [OpenAPI](https://www.opena (formerly known as Swagger). It also integrates a customized version of [Swagger UI](https://swagger.io/swagger-ui/), a nice interface rendering the OpenAPI documentation. Click on an operation to display its details. You can also send requests to the API directly from -the UI. Try to create a new _Greeting_ resource using the `POST` operation, then access it using the -`GET` operation and, finally, delete it by executing the `DELETE` operation. If you access any API -URL with the `.html` extension appended, API Platform displays the corresponding API request in the -UI. Try it yourself by browsing to `https://localhost/greetings.html`. If no extension is present, -API Platform will use the `Accept` header to select the format to use. By default, a JSON-LD -response is sent ([configurable behavior](../core/content-negotiation.md)). +the UI. Try to fetch the _Greetings_ collection using the `GET` operation, then fetch a single item. +If you access any API URL with the `.html` extension appended, API Platform displays the +corresponding API request in the UI. Try it yourself by browsing to +`https://localhost/greetings.html`. If no extension is present, API Platform will use the `Accept` +header to select the format to use. By default, a JSON-LD response is sent +([configurable behavior](../core/content-negotiation.md)). So, if you want to access the raw data, you have two alternatives: @@ -300,17 +322,17 @@ Of course, you can also use your favorite HTTP client to query the API. We are f [Hoppscotch](https://hoppscotch.com), a free and open source API client with good support of API Platform. -## Keep Your Project in Sync with the API Platform Template +## Keep Your Docker Setup in Sync -You have started a project with the API Platform template and you would like to benefit from the -latest enhancements introduced since you created your project (i.e. -[FrankenPHP](https://frankenphp.dev/)). Just use this Git based tool -[The _template-sync_ project](https://github.com/coopTilleuls/template-sync) got you covered. +The Docker and [FrankenPHP](https://frankenphp.dev/) configuration scaffolded by the installer comes +from the [Symfony Docker](https://github.com/dunglas/symfony-docker) project. To benefit from the +latest enhancements introduced upstream since you created your project, you can use the Git based +[_template-sync_ project](https://github.com/coopTilleuls/template-sync). -Run the following command to import the changes since your last update: +Run the following command from the `api/` directory to import the changes since your last update: ```console -curl -sSL https://raw.githubusercontent.com/coopTilleuls/template-sync/main/template-sync.sh | sh -s -- https://github.com/api-platform/api-platform +curl -sSL https://raw.githubusercontent.com/coopTilleuls/template-sync/main/template-sync.sh | sh -s -- https://github.com/dunglas/symfony-docker ``` Resolve potential conflicts, run `git cherry-pick --continue` and you are done! @@ -876,9 +898,15 @@ use it with the popular [RelayJS](https://relay.dev) and ## The Admin Wouldn't it be nice to have an administration backend to manage the data exposed by your API? -Wait... You already have one! +Wait... You already have one! When generated with `--with-admin`, the React-admin SPA lives in the +sibling `admin/` directory. Start its development server: + +```console +cd ../admin +npm run dev +``` -Open `https://localhost/admin/` in your browser: +Open `http://localhost:5173/` in your browser: ![The admin](images/api-platform-2.6-admin.png) @@ -899,15 +927,17 @@ Apps/Single Page Apps that you can easily tune and customize. The generator also [React Native](../create-client/react-native.md) if you prefer to leverage all capabilities of mobile devices. -The distribution comes with a skeleton ready to welcome the [Next.js](https://nextjs.org/) flavor of -the generated code. To bootstrap your app, run: +When generated with `--with-pwa`, the installer scaffolds a [Next.js](https://nextjs.org/) +application in the `pwa/` directory, ready to welcome the generated code. To bootstrap your app, run +the client generator from that directory, then start the development server: ```console -docker compose exec pwa \ - pnpm create @api-platform/client +cd ../pwa +pnpm create @api-platform/client +pnpm dev ``` -Open `https://localhost/books/` in your browser: +Open `http://localhost:3000/books/` in your browser: ![The Next.js Progressive Web App](images/api-platform-2.6-pwa-react.png) diff --git a/symfony/jwt.md b/symfony/jwt.md index fd1d3fda593..4debed0b1d9 100644 --- a/symfony/jwt.md +++ b/symfony/jwt.md @@ -26,8 +26,8 @@ You can generate them by using this command: php bin/console lexik:jwt:generate-keypair ``` -Or if you're using the [API Platform distribution with Symfony](../symfony/index.md), you may run -this from the project's root directory: +Or if you're using the [API Platform Symfony variant](../symfony/index.md) with Docker, you may run +this from the project's `api/` directory: ```console docker compose exec php sh -c ' @@ -39,9 +39,9 @@ docker compose exec php sh -c ' ' ``` -Note that the `setfacl` command relies on the `acl` package. This is installed by default when using -the API Platform docker distribution but may need to be installed in your working environment in -order to execute the `setfacl` command. +Note that the `setfacl` command relies on the `acl` package. This is installed by default in the +Docker setup of the API Platform Symfony variant but may need to be installed in your working +environment in order to execute the `setfacl` command. This takes care of keypair creation (including using the correct passphrase to encrypt the private key), and setting the correct permissions on the keys allowing the web server to read them. diff --git a/symfony/testing.md b/symfony/testing.md index 222ca2fa0ff..55d07042afb 100644 --- a/symfony/testing.md +++ b/symfony/testing.md @@ -160,12 +160,12 @@ Now that you have some data fixtures for your API, you are ready to write functi The API Platform test client implements the interfaces of the [Symfony HttpClient](https://symfony.com/doc/current/components/http_client.html). HttpClient is -shipped with the API Platform distribution. The +shipped with the API Platform Symfony variant. The [Symfony test pack](https://github.com/symfony/test-pack/blob/main/composer.json), which includes PHPUnit as well as Symfony components useful for testing, is also included. Run `composer require --dev symfony/test-pack symfony/http-client` to install the testing tools -(when using the distribution they're already installed). +(when using the API Platform Symfony variant they're already installed). Install [DAMADoctrineTestBundle](https://github.com/dmaicher/doctrine-test-bundle) to reset the database automatically before each test: @@ -382,21 +382,19 @@ Running your test suite in your [CI/CD pipeline](https://en.wikipedia.org/wiki/Continuous_integration) is important to ensure good quality and delivery time. -The API Platform distribution is -[shipped with a GitHub Actions workflow](https://github.com/api-platform/api-platform/blob/main/.github/workflows/ci.yml) +The API Platform Demo is +[shipped with a GitHub Actions workflow](https://github.com/api-platform/demo/tree/main/.github/workflows) that builds the Docker images, does a [smoke test]() to check that the application's entrypoint is accessible, and runs PHPUnit. The API Platform Demo [contains a CD workflow](https://github.com/api-platform/demo/tree/main/.github/workflows) that uses -[the Helm chart provided with the distribution](../deployment/kubernetes.md) to deploy the app on a -Kubernetes cluster. +[a Helm chart](../deployment/kubernetes.md) to deploy the app on a Kubernetes cluster. ## Additional and Alternative Testing Tools -You may also be interested in these alternative testing tools (not included in the API Platform -distribution): +You may also be interested in these alternative testing tools (not included by default): - [Hoppscotch](https://docs.hoppscotch.io/), create functional [test](https://docs.hoppscotch.io/documentation/getting-started/rest/tests) for your API Platform @@ -411,7 +409,7 @@ distribution): - [PHP Matcher](https://github.com/coduo/php-matcher), the Swiss Army knife of JSON document testing. -## Using the API Platform Distribution for End-to-End Testing +## End-to-End Testing If you would like to verify that your stack (including services such as the DBMS, web server, [Varnish](https://varnish-cache.org/)) works, you need