api-platform / api-platform/docs

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

Open
#2,318 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
181
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
20

Description

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](https://api-platform.com/docs/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.

```console
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](https://api-platform.com/docs/create-client/nextjs/) 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.

```console
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

```yaml
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: https://github.com/api-platform/api-platform/issues/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

```console
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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.