Many missing or unclear steps in the "Getting Started With API Platform with Symfony" page

[eg-goeppert]

I've tried to setup a completely new project with the api-platform installer by following the documentation for symfony Getting Started with Api Platform with Symfony but I hit a few snags.

Installing the Framework

Scaffolding the Project

Executing the following command failed because I didn't have pnpm installed.

api-platform bookshop-api --framework=symfony --with-docker --with-pwa --with-admin

There is no mention until this point that pnpm is required for the pwa. Since the documentation for the Next.js Generator mentions npm, pnpm and yarn as possible package managers I would expect that creating the project would work with just npm or yarn installed.

After installing pnpm and running the command again, the installation succeeded.

---

I then ran the following command to start the containers.

cd bookshop-api/api 
docker compose up --wait

The documentation states that two services will be spun up - php and database - but only the php service was started. It is mentioned, that the installer requires the Doctrine ORM bridge via api-platform/doctrine-orm - which is installed automatically - but that doesn't install the actual dependencies to use Doctrine or interact with the database.

Looking at the compose.yaml I can only see the php container and no database. But hidden in the compose.yaml is this comment

services:
  php:
    restart: unless-stopped
    environment:
      SERVER_NAME: ${SERVER_NAME:-localhost}, php:80
      ....
      # Run "composer require symfony/orm-pack" to install and configure Doctrine ORM
      DATABASE_URL: postgresql://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD:-!ChangeMe!}@database:5432/${POSTGRES_DB:-app}?serverVersion=${POSTGRES_VERSION:-15}&charset=${POSTGRES_CHARSET:-utf8}

so I've executed docker compose exec php composer require symfony/orm-pack to install the Doctrine ORM.

Installing this dependency modifies some files in the project. For example the Dockerfile to add the pdo_pgsql extension for php.
It adds the database service to the compose.yaml and adds a DATABASE_URL environment variable to the .env file.

These changes require the container to be rebuilt as it isn't just installing php dependencies but directly modifying the Dockerfile.

In my first attempt there was another issue after installing the orm-pack. Somehow the php container could not talk to the database container. I assume this was some networking problem and might be related to the DATABASE_URL inserted into the .env file.

It's Ready

I opened https://localhost and could access the swagger documentation. Trying out the GET /greetings route fails with a 404 error (which I have reported here: api-platform/api-platform#3003)

Bringing your Own Model

After creating the two new classes with the #[ApiResource] attribute, the documentation mentions the Web Debug Toolbar. This toolbar is not automatically installed. You need to install it with docker compose exec php composer require symfony/profiler-pack

A Next.js Web App

I switched to the pwa directory and executed pnpm create @api-platform/client. It asked for some inputs but then just printed the help page of the client generator. No actual frontend was generated.

Looking at the documentation of the client generator I should run one of these two commands

docker compose exec pwa \ 
    pnpm create @api-platform/client --resource book -g next
OR
pnpm create @api-platform/client https://demo.api-platform.com . --generator next --resource book

There is no pwa container configured through the Api Platform installer so I tried to run the second command (with https://localhost as url)
but that fails because of an invalid certificate ...

At this point I am pretty disappointed with the "onboarding" experience of api-platform and the installer.