Follow-up to #3012, taking the good half of @ili101's #3011.

--symfony-docker-ref is cherry-picked from ili101's fc625ba with authorship intact.

What's taken, and what isn't

#3011 bundled two separable changes:

1. SYMFONY_DOCKER_REF = 'main' — the default floats.
2. --symfony-docker-ref — a per-install override.

Only (2) is taken. The security and reproducibility properties live in the default, because that is what runs for everyone who types api-platform new myapp and nothing else. An escape hatch for the few who pass the flag doesn't compensate for floating the many who don't. And the rot that motivated #3008 is already handled by #3012: the pin now gets a validated bump PR the week upstream touches a file we copy.

So the default stays the reviewed SHA, and the flag overrides it per install. testSymfonyDockerRefIsPinnedToFullCommitSha is kept rather than renamed to testSymfonyDockerRefDefaultsToMain — that test is the guard rail that stops the default drifting back to a branch name.

Also dropped from the cherry-pick: everything touching --with-database, which is #3009's content and belongs in its own review.

Why the flag accepts any ref, with a warning instead of validation

The obvious hardening — "require a 40-character SHA" — buys nothing. GitHub serves an entire fork network from one object store, so a shallow fetch against the canonical repo resolves commits that were never merged, or never even opened as a PR. Verified with the exact command setupDocker runs, against the head of an unmerged PR from a fork (dunglas/symfony-docker#948, branch owned by enginydigital):

$ git remote add origin https://github.com/dunglas/symfony-docker
$ git fetch --depth=1 origin e7c96726421ce2dea2d37f37e383965044df1fff
$ git log --oneline -1 FETCH_HEAD
e7c9672 docs(mailer): drop the recipe-managed compose snippet + clarify the DSN

A hostile SHA would therefore look more trustworthy than a branch name — it points at the official repository and reads like a reproducibility measure. Format validation would be theatre, and refusing branch names would block the one case the flag exists for ("I need the fix that's on main today").

An attacker who can dictate your command line has already won, so this isn't a reason to drop the flag. It is a reason to say plainly what you're opting into:

$ api-platform new demo --with-docker --symfony-docker-ref=main

 [WARNING] Fetching symfony-docker at "main" instead of the pinned commit. This
           ref is not reviewed by API Platform, any commit from any fork of the
           repository resolves here, and the files it ships (Dockerfile,
           docker-entrypoint.sh) run on your machine. Only use a ref you trust.

The warning goes to stderr, and only fires when the ref will actually be fetched — passing it alongside --no-with-docker stays silent, since nothing is fetched.

Commits

Verification

123 tests / 239 assertions green, PHPStan clean, warning rendering checked against the real CLI.