Symfony Template

A production-ready Symfony 8.0 template with Docker, FrankenPHP, and modern development tools pre-configured.

Features

Core Stack

• Symfony 8.0 with PHP 8.4.16+
• Docker-based development with FrankenPHP and Caddy
• PostgreSQL database with Doctrine ORM
• Twig templating engine
• Asset Mapper with Stimulus for JavaScript

Authentication & Security

• User registration with email verification (SymfonyCasts Verify Email Bundle)
• Password reset functionality (SymfonyCasts Reset Password Bundle)
• Symfony Security component for authentication and authorization
• Password hashing with modern algorithms

Frontend

• TailwindCSS integration via SymfonyCasts Tailwind Bundle
• Stimulus for JavaScript interactivity
• Asset Mapper for zero-build asset management
• Form handling with Symfony Forms

Developer Experience

• Automated HTTPS in development and production
• HTTP/3 and Early Hints support
• Worker mode for blazing-fast performance with FrankenPHP
• Mercure hub for real-time messaging
• Xdebug support for debugging

Code Quality & Testing

• PHPUnit 12 with parallel testing support (Paratest)
• PHPStan static analysis with Symfony and Doctrine extensions
• PHP CS Fixer for code style enforcement
• Doctrine Test Bundle for database test isolation
• Test fixtures with Doctrine Data Fixtures and Zenstruck Foundry
• Messenger test utilities with Zenstruck Messenger Test
• Code coverage reporting

Claude Code Integration

• 5 specialized AI agents for product management, architecture, backend, frontend, and code review
• Automated workflows for creating PRs with full implementation and review
• Ticket generation from product briefs
• Enforces SOLID principles, KISS principle, and Symfony-only ecosystem

Getting Started

Prerequisites

• Docker (v2.10+)
• Docker Compose

Installation

1. Clone the repository:

git clone <your-repo-url>
cd symfony-template

2. Build the Docker images:

make build

3. Start the application:

make up

4. Open your browser:

   • Navigate to https://localhost
   • Accept the auto-generated TLS certificate (how to)

5. Stop the application:

make down

Using Make Commands

The project includes a Makefile with common commands:

make start                # Build and start the application
make down                 # Stop the application
make logs                 # View logs
make shell                # Access PHP container shell
make test                 # Run tests
make coverage             # Generate code coverage report
make php-cs-fixer--fix    # Fix code style issues
make phpstan              # Run static analysis

Development

Database Migrations

# Create a new migration
./php bin/console make:migration

# Run migrations
./php bin/console doctrine:migrations:migrate

Load Fixtures

make load-fixtures

Running Tests

# Run tests with coverage
make test

Code Quality

# Fix code style
make php-cs-fixer--fix

# Run static analysis
make phpstan

Creating Controllers, Entities, Forms

# Make a controller
./php bin/console make:controller

# Make an entity
./php bin/console make:entity

# Make a form
./php bin/console make:form

Project Structure

.
├── assets/              # Frontend assets (CSS, JS)
├── bin/                 # Executables (console)
├── config/              # Configuration files
├── migrations/          # Database migrations
├── public/              # Public web directory
├── src/
│   ├── Controller/      # Application controllers
│   ├── DataFixtures/    # Test data fixtures
│   ├── Entity/          # Doctrine entities
│   ├── Form/            # Form types
│   ├── Repository/      # Doctrine repositories
│   └── Security/        # Security-related classes
├── templates/           # Twig templates
├── tests/               # Test files
└── var/                 # Cache, logs, sessions

Configuration

Environment Variables

Copy .env to .env.local and adjust values for your local environment:

# Database configuration
DATABASE_URL="postgresql://app:!ChangeMe!@database:5432/app?serverVersion=16&charset=utf8"

# Mailer configuration
MAILER_DSN=smtp://localhost:1025

# App environment
APP_ENV=dev
APP_SECRET=your-secret-here

TailwindCSS

TailwindCSS is automatically compiled in watch mode during development. Configuration is in tailwind.config.js.

Asset Mapper

Import maps are managed in importmap.php. Add new JavaScript dependencies with:

./php bin/console importmap:require package-name

Production Deployment

Copy your project on the server using git clone, scp, or any other tool that may fit your need. If you use GitHub, you may want to use a deploy key. Deploy keys are also supported by GitLab.

Example with Git:

git clone git@github.com:<username>/<project-name>.git

Go into the directory containing your project (<project-name>), and start the app in production mode:

# Build fresh production image
docker compose -f compose.yaml -f compose.prod.yaml build --pull --no-cache

# Start container
SERVER_NAME=your-domain-name.example.com \
APP_SECRET=ChangeMe \
CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
docker compose -f compose.yaml -f compose.prod.yaml up --wait

Be sure to replace your-domain-name.example.com with your actual domain name and to set the values of APP_SECRET, CADDY_MERCURE_JWT_SECRET to cryptographically secure random values.

Your server is up and running, and a HTTPS certificate has been automatically generated for you. Go to https://your-domain-name.example.com and enjoy!

Testing

The project includes comprehensive testing setup:

• Unit tests for business logic
• Functional tests for controllers and forms
• Database test isolation with DAMA Doctrine Test Bundle
• Parallel test execution support
• Code coverage reporting with PHPUnit

Claude Code Integration

This project is designed to work seamlessly with Claude Code, Anthropic's CLI for AI-assisted development. The integration includes specialized agents and automated workflows that enforce best practices.

Development Principles

All code generated through Claude Code enforces:

• SOLID Principles - Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
• KISS Principle - Simple, straightforward solutions over complex ones
• Symfony Ecosystem Only - Only Symfony components and SymfonyCasts bundles

Specialized Agents

Five domain-expert agents are available in .claude/agents/:

Agent	Use When
product-manager	Defining requirements, user stories, prioritizing features
backend-architect	Designing system architecture, database schemas, API structures
backend-developer	Implementing controllers, services, entities, writing tests
frontend-developer	Building Twig templates, Stimulus controllers, TailwindCSS styling
code-reviewer	Reviewing code for quality, security, and best practices

Automated Workflow Skills

Three slash commands automate common workflows:

/create-tickets - Break Down Product Brief

Transforms a product brief into organized tickets with user stories and acceptance criteria.

/create-tickets              # Read from BRIEF.md
/create-tickets ROADMAP.md   # Read from specified file

Generates .claude/tickets/ folder with prioritized features (P0/P1/P2), complexity estimates, and technical tasks.

/create-pr - Create PR with Implementation & Review

Automates complete feature development from requirements to pull request.

/create-pr "implement the feature from the ticket in .claude/tickets/01-authentication.md"
/create-pr "Create admin dashboard"

What it does:

1. Invokes product-manager for requirements
2. Invokes backend-architect for design
3. Invokes developers for implementation
4. Runs quality checks (PHP CS Fixer, PHPStan, tests)
5. Creates PR targeting develop branch
6. Invokes code-reviewer for automated review
7. Auto-fixes issues and posts review comment

/review-pr - Review Existing PR

Reviews an existing pull request with automated fixes.

/review-pr        # Review current branch's PR
/review-pr 123    # Review specific PR number

Typical Workflow

# 1. Generate tickets from a product brief
/create-tickets     # Read from BRIEF.md by default

# 2. Implement a ticket (creates PR with full review)
/create-pr "implement the feature from the ticket in .claude/tickets/01-authentication.md"

Quality Gates

All automated workflows enforce:

• ✅ PHP CS Fixer passing (@Symfony rules)
• ✅ PHPStan level 9 passing
• ✅ Tests passing with ≥65% coverage
• ✅ Thin controllers, readonly services
• ✅ Security checks (SQL injection, XSS, CSRF)
• ✅ SOLID/KISS compliance

For detailed configuration, see CLAUDE.md.

License

This project is available under the MIT License.

Credits

Built with:

• Symfony
• FrankenPHP
• Docker
• TailwindCSS