symfony/demo: a reference PHP application you can read as documentation

What symfony/demo actually is, and who should read it

The repository describes itself as a reference application created to show how to develop applications following the Symfony Best Practices, and it points at the official Symfony Book for the reasoning behind those practices. That framing matters. This is not a framework, not a bundle, and not a scaffold generator. It is a small blog application, written in PHP, that exists so the rules in the best-practices document have a concrete example attached to them.

The audience is therefore narrow and specific. If you have read the best-practices chapter and want to see where controllers, services, templates, translations and assets are supposed to live, the directory layout answers that faster than prose does. If you are onboarding a team onto Symfony conventions and need one artifact everyone can open, this is that artifact. If you are looking for a CMS, a blog engine to deploy, or a foundation for a client project, you are in the wrong repository, and the rest of this article explains why.

The layout is the lesson: config, src, templates, translations, assets

The top-level entries are the real content of the project. config/ holds the framework and application configuration, src/ holds the PHP code, templates/ holds Twig templates, translations/ holds message catalogs, assets/ holds front-end sources compiled through importmap.php, and public/ is the document root with the front controller. tests/ and phpunit.dist.xml define the test setup, and the README gives a single command to run it.

Several files say as much about intent as the directories do. There is a phpstan.dist.neon plus a phpstan-baseline.neon, so static analysis is configured and a baseline of accepted findings is checked in. There is .php-cs-fixer.dist.php, so coding style is enforced by a tool rather than by review comments. There is a .devcontainer/ directory, so the project ships a container definition for editor integration. There are separate .env, .env.dev, .env.test and .env.local.demo files, which is how Symfony separates environment configuration, and a data/ directory that holds the SQLite database used by the demo.

That combination is the point. A reader can trace a single request from public/ through config/ into src/, out to templates/, and see the environment, style, static analysis and test configuration that surround it. Few tutorials show all of those layers in one place, and that is the argument for reading a repository instead of a blog post.

Installing symfony/demo and running it locally

The README lists three installation routes. The first uses the Symfony CLI binary and creates a project named my_project from the demo skeleton. Run it in the directory where you want the project to appear; it will create the folder for you.

symfony new --demo my_project

The second route uses Composer directly, and is the one to pick if you already have Composer and do not want the Symfony CLI. The README also documents a third variant, cloning the repository and running composer install inside it, which is what you want if you intend to read the git history alongside the code.

composer create-project symfony/symfony-demo my_project

Once the project exists, the README states there is no need to configure anything before running it. With the Symfony CLI installed, start the development server from inside the project directory:

cd my_project/
symfony serve

The application is then reachable in a browser at the URL the command prints, https://localhost:8000 by default. If you would rather not install the Symfony CLI, the README gives the built-in PHP server as an alternative, pointed at the public/ directory so that the front controller is the entry point:

cd my_project/
php -S localhost:8000 -t public/

To confirm the checkout is healthy before you start changing things, the README documents a single test command. Run it from the project root and read the output; a passing run means the environment satisfies what the test suite expects.

cd my_project/
./bin/phpunit

Before any of this, check the requirements section: PHP 8.2.0 or higher, the PDO-SQLite PHP extension enabled, and what the README calls the usual Symfony application requirements. The SQLite requirement is easy to miss on a minimal PHP image, and without it the demo database in data/ cannot be opened.

It is a demonstration blog, not a production starting point

The honest limitation is in the name. This is a demo application, and the README never claims otherwise. It does not document deployment, it does not document a database migration path to a server database, and it does not document an upgrade procedure for the application itself when a new Symfony major version arrives. What the README does document is local running and a test command. Everything past that is left to the reader.

The SQLite dependency is the concrete consequence. The requirements list PDO-SQLite, and the repository carries a data/ directory for the demo database. A real application that expects PostgreSQL or MySQL will need to change configuration and probably code, and none of that work is described in the repository. Treat the persistence layer as an example of how to wire Doctrine, not as something to keep.

The static analysis baseline is a second signal worth reading carefully. A checked-in phpstan-baseline.neon means the project accepts a set of existing findings rather than fixing them all. That is a normal, defensible choice for a demo, and it is also a reminder that the code is written to be read, not to pass the strictest possible gate. Do not copy the baseline into a new project and assume it reflects your own standards.

Finally, the demo tracks Symfony itself. The most recent release listed is v3.1.0 from 2026-06-25, and the last push to the repository was on 2026-09-16. That is recent activity, but the version you get from composer create-project depends on what composer.lock pins at the moment you run it. If you build on this code, you inherit whatever Symfony version that lock file names, and you inherit the upgrade work that follows from it.

symfony/demo versus starting from symfony/skeleton

The natural alternative is the plain Symfony skeleton, which is what symfony new produces without the --demo flag. The difference is not quality, it is scope. The skeleton gives you an empty application: the framework, a default configuration, and nothing else. You add every controller, template, entity and translation catalog yourself, and you make every structural decision on your own.

The demo gives you the opposite. It arrives with a working blog, complete templates, translation files, a test suite, static analysis configuration, a coding-style configuration and a container definition. You can read a finished example before you write a line of your own code.

Which one you want depends on what you are trying to learn. If your question is "where does this kind of file go in a Symfony project", the demo answers it immediately and the skeleton does not. If your question is "what is the minimum I need to start my own application", the skeleton is the honest answer and the demo is noise you will spend an afternoon deleting. The demo's own structure is not a template to trim down; it is a finished shape that assumes a blog.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-16, so the project is being kept current. Releases are tagged: v3.1.0 on 2026-06-25, v3.0.2 on 2026-05-27, v3.0.1 on 2026-02-02. The gap between v3.0.1 and v3.0.2 is roughly four months, and the gap between v3.0.2 and v3.1.0 is about a month, so the cadence is irregular rather than scheduled. Nothing in the repository commits to a support window or a long-term branch.

For a reader, that cadence is fine. For anyone treating the code as a base, it means the upgrade cost is set by Symfony's release cycle, not by this repository's. When Symfony moves, the demo moves with it, and the diff between two demo tags is effectively a worked example of the migration. That is arguably the most valuable thing here, and it is not something the README advertises.

The licence is MIT, stated in the repository metadata and present as a LICENSE file at the top level. MIT is permissive: it allows reuse, modification and redistribution, and it requires that the copyright notice and permission notice be preserved. It offers no warranty. This is a description of the licence text, not legal advice; if you intend to ship the code in a commercial product, read the LICENSE file and, where it matters, take your own advice.

Editorial conclusion

Adopt symfony/demo if you learn best by reading a complete, runnable Symfony application and want to see the best-practice layout in one place, or if you are teaching that layout to a team. Do not adopt it as the base of a production product: it is a demonstration blog with SQLite and no documented deployment or upgrade path, and its structure reflects the practices of the Symfony version it tracks. Before you build on it, verify three things: that your PHP is 8.2.0 or higher and the PDO-SQLite extension is enabled, that composer create-project symfony/symfony-demo or symfony new --demo still resolves against the current release, and which Symfony version the v3.1.0 tag pins in composer.lock, because that is what determines how much of the code you will have to change when you upgrade.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. symfony/demo on GitHub