Thelia 3: an e-commerce framework on Symfony 7 and API Platform

This is the framework repository, not the shop template

The first paragraph of the readme is a warning that saves you a wasted afternoon. This is the development repository of Thelia, the open source e-commerce framework, and work on Thelia itself goes there. To create a shop you use the project skeleton instead, which lives in the separate thelia/thelia-project repository. The distinction matters because the two repositories are used differently: the framework repository is where you develop the framework or contribute a module, and the skeleton is what a store owner starts from. The project describes itself as an open source framework for building online stores and managing web content, and the version 3 stack is PHP 8.3, 8.4 or 8.5, Symfony 7.4 LTS, API Platform 4.3 in standalone mode, the Propel ORM, a Twig front office in the Flexy theme, a Twig back office in the default-twig theme, and Lexik JWT for API authentication. The licence is GPL-3.0 and the last push was on 2026-10-18.

The version 3 stack, and what the back office change cost

The stack list is where a version 3 upgrade shows itself. The back office and the front office are both built with Twig, Symfony UX covering Stimulus, Twig Components and Live Components, and Bootstrap 5, so version 3 dropped the Smarty templates of the previous generation. The consequence for existing sites is stated in the back office templates section: Thelia 3 installs one back office, the Twig one, and the Smarty back office of Thelia 2 is no longer installed nor maintained in 3.x. If you maintain a module, the migration guide is at the documentation site. There is also a note in the repository that the security support window for each release series is listed in SECURITY.md, which is the file to read if you are deciding which series to run. The topics list confirms the shape of the project, with api-platform, cms, e-commerce, mariadb, mysql, php, symfony and twig.

Requirements, and the document root rule

The requirements table is specific and includes the versions, not just the names. PHP 8.3, 8.4 or 8.5, with 8.3 recommended. The database is MariaDB 10.11 or later, also recommended, or MySQL 8.x. The PHP extensions needed are pdo_mysql, openssl, intl, gd, curl, dom, mbstring and zip. Composer must be 2.7 or later. The web server is Nginx or Apache with the document root set to public/. That last point is the one that catches newcomers, because a Symfony application with a front controller and a public directory does not work if the document root is left at the project root, and the security of the application depends on nothing outside public/ being reachable over HTTP.

DDEV is the development path, and there is no Docker setup

The repository does not ship a Docker setup, and the maintainers use DDEV, which provides PHP 8.3, MariaDB 10.11 and Node.js 20 in one command. Any equivalent stack works, the requirement being that you point your web server at public/ and use the same PHP 8.3 binary for the command line and for the web server, which is a detail that catches people out when the CLI and the web server disagree about versions. The configuration and start commands are:

ddev config --project-type=php --php-version=8.3 --database=mariadb:10.11 --docroot=public --nodejs-version=20
ddev start
ddev exec composer install

The docroot flag is the same public/ setting as the requirements table, and specifying the Node.js version matters because the asset build needs it. There is a .ddev directory in the repository and a .env and .env.test at the root, so some environment configuration is committed and the rest is layered on top.

bin/install takes its database credentials from the environment

The installer reads its database credentials from the DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER and DATABASE_PASSWORD environment variables, or from command line flags, and with DDEV the database is reachable as db:3306 with user db and password db. The install command sets the themes and the demo data and the administrator account:

ddev exec bin/install \
  --frontoffice_theme=flexy --backoffice_theme=default-twig \
  --pdf_theme=default --email_theme=default \
  --with-demo --with-admin \
  --admin_login=thelia --admin_password=thelia \
  --admin_first_name=Admin --admin_last_name=User \
  [email protected]

The theme flags are the thing to think about, since they select the front office and back office templates you will actually be running. The --with-demo and --with-admin flags seed sample content and create the administrator account, and the login and password you pass here are the credentials you will then use, so the values in the example are obviously not what you should ship. Without DDEV you export the database variables, or put them in .env.local, and run php bin/install with the same flags.

The installer builds the assets, and you can rebuild them by hand

One of the less obvious things about the setup is that bin/install compiles the assets itself, so a fresh install has working front office JavaScript and stylesheets without a separate step. It runs importmap:install and tailwind:build for the active front office theme, and sass:build for the back office stylesheet. To rebuild them later you run the same commands from the application root:

ddev exec php bin/console importmap:install   # front-office JavaScript dependencies
ddev exec php bin/console tailwind:build      # front-office stylesheet (Flexy)
ddev exec php bin/console sass:build          # back-office stylesheet (default-twig)

The comments in that block are worth reading because they tell you which artifact each command produces, and the split between importmap and Tailwind for the front office and Sass for the back office is not something you would guess. Once the assets are in place, the storefront is served at the project domain and the admin at the admin path on the same host. The application root also holds a rector.php for automated refactoring, a cliff.toml for the changelog, infection configuration for mutation testing and a set of PHPStan baseline files, which tells you the static analysis story is layered rather than a single pass.

Three quality gates, and how the code is split up

The quality commands are three and they are run through composer inside the development environment:

ddev exec composer test       # PHPUnit test suites
ddev exec composer cs-diff    # coding standard (php-cs-fixer)
ddev exec composer phpstan    # static analysis

The cs-diff name is the one to note, because it is a check that reports a diff rather than a check that simply passes, which is how you see what the formatter would change. The repository also carries separate phpunit configuration files, one for the legacy suite and one for the current distribution, and a .php-cs-fixer.dist.php with the coding standard rules. The packaging is split across repositories and the readme is specific about it: several packages are split out of this repository, thelia/core, thelia/config and thelia/setup, modules live under the thelia-modules organisation, and the Flexy front office theme is in its own repository, thelia/Flexy. That means a project assembled from the skeleton is pulling in several repositories rather than one, and the split is where a custom theme or a custom module goes.

Editorial conclusion

Thelia suits a PHP team that wants a shop with a real back office, an API and a Twig theming layer, and that is prepared to work inside the Symfony and API Platform stack rather than beside it. It does not suit a project that wants a plain content management system with a catalogue bolted on, and it does not suit a team that needs its own data layer, since Propel is baked in. Before you start, check the security support window for your release series in the SECURITY.md file, and note that the repository does not ship a Docker setup, so you will need to assemble or use a development environment yourself.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. thelia/thelia on GitHub