Skip to main content
Version: Next

Contribute

Thelia is hosted on GitHub. To contribute, fork the repository and open a pull request, or report a problem in the issue tracker.

Set up a development checkout​

Clone the repository and install it with DDEV, which is the setup the project is tested against:

git clone https://github.com/thelia/thelia.git
cd thelia

ddev start
ddev composer install
ddev exec php bin/install --frontoffice_theme=flexy --with-demo --with-admin
ddev exec bash -c "cd templates/frontOffice/flexy && npm install && npm run build"
ddev exec bash -c "cd templates/backOffice/default-twig && npm install && npm run build"

See DDEV Installation for the full setup, or Standard Installation if you prefer a local PHP and MySQL stack.

Coding standards​

Thelia 3 targets PHP 8.3 and follows PSR-12, through the Symfony ruleset of PHP CS Fixer. The configuration lives in .php-cs-fixer.dist.php at the root of the repository, so you never have to configure the rules yourself:

ddev exec composer cs-diff    # report violations without changing anything
ddev exec composer cs         # fix them in place

New PHP files declare strict types:

<?php

declare(strict_types=1);

Before opening a pull request​

Three checks must be green. Run them before you push, because the CI runs the same ones:

ddev exec composer cs-diff    # coding standards
ddev exec composer phpstan    # static analysis
ddev exec composer test       # the full test suite

composer test prepares a dedicated test database, then runs the unit, integration, api, http-flexy and http-backoffice suites. It never touches your development database. composer ci chains the three commands in one call.

If PHPStan reports errors on generated Propel classes that you did not touch, its result cache is likely stale; composer phpstan-fresh clears it and re-runs the analysis.

See Testing for how to write tests and what each suite covers.

Pull request workflow​

Fork Thelia, then work on a branch. Never commit on main: keep it in sync with the upstream repository.

git checkout -b my-branch main

Once your work is done, rebase it on the current main and push it to your fork:

git remote add upstream https://github.com/thelia/thelia.git
git checkout main
git pull --ff-only upstream main
git checkout my-branch
git rebase main
git push origin my-branch

Then open the pull request as described in the GitHub documentation.

A few things make a pull request easier to review:

  • One concern per pull request. Unrelated fixes belong in separate ones.
  • Commit messages in English, one line, prefixed with the type of change (feat:, fix:, docs:, refactor:, test:, chore:).
  • A change in behaviour comes with a test that fails without the fix.
  • Do not reformat code you are not changing: it hides the actual diff.

Changing the database schema​

The Propel schema of the core models is local/config/schema.xml. After editing it, regenerate the model classes and the SQL that bin/install applies:

# generate the Propel base classes
vendor/thelia/propel/bin/propel build -v \
    --input-dir=local/config/ --output-dir=core/lib/ --enable-identifier-quoting

# generate setup/thelia.sql
vendor/thelia/propel/bin/propel sql:build -v \
    --input-dir=local/config/ --output-dir=setup/
rm setup/sqldb.map

Commit the regenerated classes and setup/thelia.sql along with your schema change. An existing installation is not migrated by these files: add the corresponding statements to an update script in setup/update/sql/ so that stores already in production can upgrade.

For a module, the equivalent commands are module:generate:model and module:generate:sql, which read the module's own schema.xml. See the CLI reference.

Translations​

The core strings ship as PHP catalogs in core/lib/Thelia/Config/I18n/{locale}.php; a template or a module carries its own I18n/{locale}.php. These versioned files are the ones a contribution touches. Merchant edits made in the back-office go to local/I18n/, which is not versioned and is never part of a pull request.

When you add a translatable string, add it at least to en_US.php in the same pull request, so no release ships an untranslated key. See Internationalization for the domains, the fallback rules and the back-office translation screen.

Contributing to this documentation​

The documentation lives in thelia/docs and is built with Docusaurus. Every page has an Edit this page link at the bottom that opens the right file on GitHub.