README

About 🖋

MicroSymfony is a Symfony 8.1 application template on steroids, ready to use.

I have made a long blog post explaining the philosophy behind it and how to use it:

• Introducing the MicroSymfony application template

Note

PS: If you want to use the last Symfony 7.4 LTS version, follow the procedure in agents/downgrade-to-symfony-7-4-LTS.md.

Alternatively, if you have an AI coding assistant tool installed, you can run:

opencode --prompt agents/downgrade-to-symfony-7-4-LTS.md

Table of Contents 📖

• Demos
• Quick-start
  • With the Symfony binary
  • With FrankenPHP
  • With Laragon
• Requirements
  • Optional requirements
• Stack
• Features
• Feature branches
  • Minimalistic-versions
  • Infrastructure
  • Database
  • Tooling
• Notes
  • Symfony UX
  • PHP configuration files
• Other good practices
• ADR
• References
• Contributing
• Security
• Credits
• License
• Built with MicroSymfony

Demos 🌈

Because a live demo is always better than all explanations:

• Live demo powered by Apache2 / PHP-FPM https://microsymfony.ovh
• Live demo powered by FrankenPHP at https://frankenphp.microsymfony.ovh

Quick-start ⚡

With the Symfony binary 🎶

You must have the Symfony binary and Composer installed locally.

To create a new project from the last tag, run:

composer create-project strangebuzz/microsymfony && cd microsymfony

Then start the PHP server with make:

make start

Or with Castor:

castor start

Open https://127.0.0.1:8000 (considering your 8000 port is free) and enjoy! 🙂

Note

PS: You can also use the green button "Use this template ⇩" at the top right of the GitHub project homepage. It creates a new repository from the main branch instead of the last release. I guarantee that all commits on the main branch are stable; you can verify that the associated CI jobs are ✅.

With FrankenPHP 🧟‍

We can also use FrankenPHP to run MicroSymfony. You must have Docker installed locally.

Create a new project from the GitHub template, run:

docker run --rm -it -v $PWD:/app composer:latest create-project strangebuzz/microsymfony && cd microsymfony

Then run:

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 \
    -d \
    dunglas/frankenphp

Open https://localhost and enjoy! 🙂

PS: On Windows, replace $PWD with "%cd%".

Note: FrankenPHP already uses PHP 8.5.

With Laragon

Have a look at the specific documentation.

Requirements ⚙

• At least PHP 8.4 and the Symfony CLI
• Or Docker

Optional requirements 🚦

• The Xdebug PHP extension if you want to run the code coverage report
• Castor task runner, if you would rather not use Make and its Makefile

Stack 🔗

• PHP 8.4 or PHP 8.5
• Symfony 8.1
• Doctrine ORM 3 (DBAL 4)
• Twig 3
• Hotwired Stimulus 3.2 and Turbo 8.0
• PHPUnit 13
• Pico CSS 2.1

Features 🚀

MicroSymfony ships these features, ready to use:

• Two task runners
  • Make (source) (demo) (output)
  • Castor (source) (demo) (output)
• Static analysis with PHPStan 2
  • Configuration
• Coding standards with php-cs-fixer
  • Configuration
• Tests (demo)
  • Unit test example
  • Integration test example
  • Functional test example
  • API test example
  • E2E test example
• Code coverage at 100% (configurable threshold)
  • Coverage report on Scrutinizer
• GitHub CI (actions)
  • Tests job output
  • Lint job output
  • Security job output
• AssetMapper+Stimulus (documentation)
  • Vanilla JS (source) (demo)
  • Fetches JSON data from an application endpoint (source) (demo)
• A custom error template
  • Source
  • Demo

Feature branches 🚅

Feature branches are not merged into the main branch but are used to test the integration of a new vendor library or make a POC. For example, have you ever dreamed of testing Eloquent, the Laravel ORM, on a Symfony project? Then clone the eloquent branch and run composer install && make load-fixtures.

Minimalistic versions

• Doctrine less (PR, branch, rebased on 2026-01-17)
• Symfony 7.4 LTS (PR, branch, rebased on 2026-02-07)

Infrastructure

• Symfony-docker (PR, branch, rebased on 2024-11-17)

Database 💽

These « database » branches aim to display a list of records from an SQLite database.

• Eloquent ORM (PR, branch, rebased on 2024-11-17)

Tooling 🔨

• Vite-Bundle (PR, branch, rebased on 2026-02-11) (demo)
• Psalm (PR, branch, rebased on 2026-01-18)
• Taskfile (PR, branch, rebased on 2024-12-04)
• TwigStan (PR, branch, rebased on 2024-11-18)
• Twig-CS-Fixer (PR, branch, rebased on 2026-12-30)

One will rebase those branches regularly so they are not too outdated.

Notes 📒

Symfony-UX

Turbo forms are disabled in assets/app.js. To enable the feature for a given form, add the data-turbo="true" attribute to it. Or change the parameter Turbo.setFormMode to on to activate the feature globally. In both cases, your controller code has to be modified accordingly.

PHP configuration files

If you install a new Symfony library, the Flex recipes can add YAML files to your project. These YAML files are loaded, but you can convert them to PHP like the other configuration files. Take examples from the other files in config/packages to see how to make the conversion.

Other good practices 👌

• Using PHP configuration files instead of YAML (source)
• Using strict types in all PHP files (source)
• Using the ADR pattern in an action controller (source) (doc)
• The composer.json file is normalized with ergebnis/composer-normalize
• Use of the composer bin plugin to install and run php-cs-fixer

ADR 📝

ADR stands for Architecture Design Records:

• [2026-01-17] Use Doctrine ORM as the default database layer (PR)
• [2025-12-29] Use the new PHP configuration (PR)
• [2025-01-25] Include the FrankenPHP runtime by default (PR)
• [2025-01-21] Add PHPUnit test suites (PR)
• [2024-12-18] Use PicoCSS instead of BareCSS as the CSS framework (PR)
• [2024-12-05] Convert all configuration files to PHP (fluent interface) (PR)
• [2024-09-22] Use the ADR pattern for all controllers (PR)

References 📚

• Running a Symfony app on a VPS with Docker and FrankenPHP (les-tilleuls.coop)
• How to Switch from YAML Configs to PHP Today with Symplify (tomasvotruba.com)
• PHPStan 2.0 Released With Level 10 and Elephpants! (phpstan.org)
• A better ADR pattern for your Symfony controllers (strangebuzz.com)
• My Taskfile configuration for Symfony (jmsche.fr)
• You should be using PHPStans bleeding edge (backendtea.com)
• A Good Naming Convention for Routes, Controllers and Templates? (jolicode.com)
• Front-end application development, Symfony-style(s) (dunglas.dev)
• Automated Test Coverage Checks with Travis, PHPUnit for Github Pull Requests (ocramius.github.io)
• Installing and using php-cs-fixer (strangebuzz.com)
• Castor, a journey across the sea of task runners (jolicode.com)
• Initializing your Symfony project with solid foundations (strangebuzz.com)
• Organizing your Symfony project tests (strangebuzz.com)
• What are your Symfony best practices? (strangebuzz.com)
• Setting a CI/CD workflow for a Symfony project thanks to the GitHub actions (strangebuzz.com)
• The Symfony Framework Best Practices (symfony.com)

Contributing 🤝

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security 🧯

Please see SECURITY for details.

Credits 🙏

• COil (primary maintainer)
• All Contributors

Made with contrib.rocks.

License ⚖️

The MIT License (MIT). Please refer to the license file for more information.

Built with MicroSymfony 🛠️

• Placehold.ovh (2024-12-01)
• Appartement-tourcoing.com (2024-11-30)
• Easyadmin Mercure Demo (2023-05-24)