README

Pragmatic FrankenPHP is a PHP 8.5 / Symfony 8 / FrankenPHP starter that real production projects actually grew out of — and the lessons were ported back. Vertical Slices + CQRS over Messenger, PostgreSQL 17, worker mode, real prod image, supply-chain attestations. The goal: fork it and ship a real product on day one, operated by humans and AI agents alike.

The promises are CI-proven, not vibes:

• the production image boots on every PR (prod-image job: build → run → /ready);
• scaffolded code passes PHPStan 10 + tests untouched (agent-smoke job);
• release images carry SLSA build provenance, and the deploy gate verifies it (ADR-0014);
• docs are linted against reality (make docs-check: routes, Makefile targets, ADR sync).

For architecture rules and code-level guidance, see AGENTS.md — the single source of truth, ≤ 2 000 tokens, equally usable by developers and AI tools.

Stack

Quickstart

Path 1 — template + Docker (nothing but Docker needed):

gh repo create my-app --template k2gl/pragmatic-franken --clone && cd my-app
# or: git clone https://github.com/k2gl/pragmatic-franken.git my-app
make install                  # env, containers, deps, migrations
make init name=my-app         # rename + real secrets (optionally: prune=1 reset-git=1)
make smoke                    # bin/console + /ready

Path 2 — composer create-project (needs PHP ≥ 8.5 on the host):

composer create-project k2gl/pragmatic-franken my-app
cd my-app && make install && make init name=my-app

The app comes up at https://my-app.localhost:${HTTPS_PORT:-4750} (browsers resolve *.localhost automatically — no /etc/hosts edits). Try the example API: POST /tasks, GET /tasks, POST /tasks/{id}/complete — completion pushes a Mercure live update on /tasks.

Why not just symfony/skeleton?

Honest non-goals: no auth in core (recipe instead), no bundled SPA, no Kubernetes, no multi-DB.

Daily commands

Project layout

src/                              # application code
  Kernel.php                      # App\Kernel (Symfony MicroKernel)
  SharedKernel/                   # cross-context infra (repository base, problem+json listeners)
  Context/{Name}/                 # bounded contexts: Entity/, Repository/, Features/{Feature}/
    Health/Features/Healthz/      # reference slice (JSON, /healthz + /ready)
    Home/Features/Index/          # reference slice (Twig + AssetMapper, /)
config/  bin/  public/  assets/   # standard Symfony layout
migrations/                       # Doctrine migrations
docs/                             # ADRs and guides (Tier 2)
  adr/                            # ADRs with YAML front-matter
  guides/                         # development, testing, worker-mode, …
dev/                              # codegen helpers (create-slice, new-adr, check-docs)
ops/                              # deployment scripts
tests/                            # mirrors src/ — tests/Context/{Name}/Features/{Feature}/
docker/                           # Dockerfile, Caddyfile, php.ini
AGENTS.md                         # Tier-1 agent context, ≤ 2 000 tokens

The example slices (Health/Healthz, Home/Index, Task) are reference implementations — Healthz is normative for ADR-0005 health checks, Task for the full entity → migration → factory → tests vertical; Home/Index is non-normative (drop it for API-only or SPA projects).

Architecture decisions

All decisions live in docs/adr/. Each ADR carries YAML front-matter (status, date, audience, summary) so agents can skim without loading the full body.

Guides

• docs/guides/development.md — daily commands, slice scaffolding details
• docs/guides/testing.md — concrete PHPUnit + Foundry + Messenger-Test patterns
• docs/guides/worker-mode.md — debugging FrankenPHP worker behavior
• docs/guides/mercure-integration.md — real-time SSE via FrankenPHP's built-in Mercure hub
• docs/guides/sdk-generation.md — auto-generate TypeScript types from PHP Result DTOs
• docs/guides/deployment.md — single-VDS topology, zero-downtime rollout
• docs/guides/disaster-recovery.md — backups and the restore drill
• docs/guides/parallel-sessions.md — isolated worktree stacks for parallel agents
• docs/guides/supply-chain.md — sign releases, verify before deploying

Recipes (opt-in capabilities)

Proven in real production projects grown from this skeleton, documented instead of bundled: JWT auth · feature flags · SPA frontend · preview environments.

Staying close to the template

Forks don't merge templates — they apply changes. Each release ships an UPGRADE.md entry with the few changes worth porting; see docs/guides/fork-maintenance.md.

AI agents

The repository ships with a single AGENTS.md at the root, intended to be read by every AI tool by convention. There are no .cursorrules, .windsurfrules, .cursor/rules/* or per-tool prompt files — see ADR-0010 for the rationale.

Machine-local Claude Code settings live in .claude/settings.local.json (gitignored); parallel agent sessions get isolated stacks via dev/worktree.sh (ADR-0017).

Contributing

See .github/CONTRIBUTING.md. Conventional Commits required for the message header. CI gates: Pint, PHPStan level 10, PHPUnit. make ci mirrors the pipeline locally.

License

MIT.