README

A production-ready Symfony 8 starter kit. Everything you need to ship a real application — authentication, admin panel, async messaging, and modern frontend tooling — pre-wired and ready for your domain.

composer create-project boatware/symfony-starter my-app
cd my-app && make setup
open http://localhost:9161

What's included

Quick start

Prerequisites

• Docker ≥ 24
• Composer ≥ 2

1. Create the project

composer create-project boatware/symfony-starter my-app
cd my-app

composer create-project automatically copies .env.dist → .env and generates a fresh APP_SECRET.

2. Review .env

Open .env and adjust anything that needs to change (database name, port, mailer settings, …). Defaults work out of the box for local development.

3. Start the stack

make setup

This builds the Docker image, installs PHP and JS dependencies, builds frontend assets, runs database migrations, and seeds the database.

4. Open the app

http://localhost:9161

5. Log in

Change these passwords immediately on any non-local environment.

Development

Container commands

All PHP commands run inside the php container:

docker compose exec php bin/console <command>
docker compose exec php composer <command>
docker compose exec php bun run <script>

Make targets

make setup         # First-time setup
make start         # Start containers
make stop          # Stop containers
make destroy       # Remove containers (keep volumes)
make destroy-volumes  # Remove containers AND data volumes

make lint          # PHP syntax check
make phpcs         # Fix code style
make phpcs-dry     # Check code style (dry run)
make phpstan       # Static analysis (PHPStan)
make psalm         # Static analysis (Psalm)
make test          # Run full test suite
make qa            # All checks + tests

make cache         # Clear Symfony cache
make auto-migrate  # Generate + run DB migration
make reset-database  # Drop, recreate, migrate, seed

make generate-secret  # Regenerate APP_SECRET in .env
make start-messenger  # Start async worker manually

Asset pipeline

Assets are compiled with Webpack Encore, run by Bun (instead of npm):

docker compose exec php bun run dev     # Development build
docker compose exec php bun run watch   # Watch mode
docker compose exec php bun run build   # Production build

Database

The default database URL points to the PostgreSQL container.
For a local connection (e.g. from a GUI client), check the DB_PORT in .env (default 5432).

Sending emails

In development all emails are intercepted by Mailpit at http://localhost:8025. No emails leave your machine.

Architecture

Directory structure

src/
  Command/          CLI commands
  Controller/       HTTP layer — all extend BaseController
  DataFixtures/     Foundry factories + stories (groups: dev, test)
  Entity/           Doctrine ORM entities (final, UUID PKs)
  Enum/             PHP 8.1 enums (Role, LogLevel)
  EventSubscriber/  Locale detection, session debug, preview reset
  Exception/        EntityMismatchException
  Form/             FormTypes + DTOs
  Message/          Messenger message classes (async/sync)
  MessageHandler/   Corresponding handlers
  Monolog/          DoctrineLogHandler (writes to DB)
  Pagination/       Generic pagination helper
  PHPStan/          Custom PHPStan rules
  Repository/       Data access layer
  Security/         UserChecker
  Service/          Business logic (Mailer, ContentRenderer, DiskSpace, Validators)
  Twig/             AppExtension

Key conventions

Entities — final, implement EntityInterface (toArray()), UUID primary key via PHP 8.4 asymmetric visibility (public private(set) Uuid $id).

Repositories — implement RepositoryInterface, expose save() / delete() (throw EntityMismatchException on wrong type).

Controllers — extend BaseController, use #[Route] attributes, #[IsGranted] for auth, #[CurrentUser] for injection.

Forms — edit flows use DTOs; Service/DTO/ services handle entity↔DTO conversion.

Translations — translations/messages+intl-icu.{en,de}.yml for application messages, security+intl-icu.{en,de}.yml for authentication.

Content pages — static Markdown files in content/{locale}/ rendered via ContentRenderer (supports front-matter for template selection).

Custom PHPStan rules

Three rules are enforced in src/PHPStan/Rules/:

Configuration

Environment variables

Changing the app name

Update app.name in translations/messages+intl-icu.en.yml (and .de.yml). Also update MAILER_FROM_NAME in .env.

Adding locales

1. Add the locale to app.locales in config/services.yaml
2. Create translations/messages+intl-icu.{locale}.yml
3. Create translations/security+intl-icu.{locale}.yml
4. Create content/{locale}/ with imprint.md and privacy.md
5. Add email templates under templates/emails/{locale}/

Testing

make test           # Full suite (prepare-test + pest)

Tests are split by type:

Deployment

Production with Docker

make restart-prod

This rebuilds the production image, installs prod-only PHP/JS deps, runs migrations, and warms the cache.

Environment

Copy .env.dist to .env on the server and set:

APP_ENV=prod
APP_SECRET=<long-random-string>
DATABASE_URL=postgresql://...
MAILER_DSN=smtp://your-smtp-server

FrankenPHP HTTPS

To enable automatic TLS, change SERVER_NAME in your environment:

# Single domain
SERVER_NAME=example.com

# With www redirect
SERVER_NAME=example.com, www.example.com

FrankenPHP (via Caddy) will obtain and renew Let's Encrypt certificates automatically.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.md.