terminal42/contao-build-tools

Highly opinionated build tool setup for Contao websites.

dev-main 2023-12-01 15:57 UTC

Requires

• composer-plugin-api: ^2.0
• composer/semver: ^3.0
• symfony/filesystem: ^3 || ^4 || ^5 || ^6

Requires (Dev)

• composer/composer: ^1.1 || ^2.0
• deployer/deployer: ^7.0
• sentry/sentry-symfony: ^4.0

MIT

• terminal42 gmbh

• ci
• contao
• code-style
• rector
• cq

README

This is an experimental repository to ease configuration of Contao bundles and websites.

DO NOT USE IN PRODUCTION

Summary

This repo contains some highly opinionated configurations for our extensions and websites. The CQ and CS tools currently assume that your bundle or application is set up according to Symfony Best Practice for applications or bundles, meaning there is an src/ directory where all your application or bundle code lives in, but none of the configuration.

Code Quality and Code Style

This package automatically configures the root project for code quality and code style tools. Whenever you run composer install or composer update on the project, it will also update the build tools automatically. The following tools are currently available and can be executed through the composer run command:

Code Style Fixer

The cs-fixer script will fix the coding style in the src/ directory according to the latest Contao coding standards.

You can also run check-cs to only run a code style check without applying fixes (e.g. for build tools).

Rector

The rector script will automatically upgrade the code to match the latest Contao standards.

PHPStan

The phpstan script will check your code with PHPStan.

By default, the config uses PHPStan Level 6 to validate your code. There are two ways to adjust this

1. Call the command with a level parameter, e.g. composer phpstan -- --level=4
2. Configure the PHPStan level in your composer.json extra section

   {
        "extra": {
            "contao-build-tools": {
                "phpstan-level": "4"
            }  
        }
   }

Ideas

Ideas for additional tools that could be integrated:

• maglnet/composer-require-checker
• https://github.com/VincentLanglet/Twig-CS-Fixer

Deploying Contao websites

We use Deployer do deploy Contao website to live servers.

To use the Deployer helper, you first need to require Deployer in your composer.json

{
    "require-dev": {
        "terminal42/contao-build-tools": "dev-main",
        "deployer/deployer": "^7.0"
    }
}

Example deploy.php

<?php

require_once 'vendor/terminal42/contao-build-tools/src/Deployer.php';

use Terminal42\ContaoBuildTools\Deployer;

(new Deployer('example.org', 'ssh-user', '/path/to/php'))
    ->addTarget('prod', '/path/to/deployment', 'https://example.org')
    ->buildAssets()
    ->includeSystemModules()
    ->addUploadPaths(
        // some additional directory
    )
    ->run()
;

Error tracking with Sentry.io

The Terminal42\ContaoBuildTools\ErrorHandlingTrait adds useful Sentry helpers.

• ErrorHandlingTrait::sentryOrThrow will either log an error/exception to sentry, or it will throw an exception if Sentry integration is not available (e.g. on localhost or in dev environment). It is mostly useful when running looping cronjobs, like synchronizing Contao with a remote system, so an error on syncing a record will not prevent the sync loop from finishing other records.

• ErrorHandlingTraig::sentryCheckIn has been added for the new Sentry Cron job monitoring. Call sentryCheckIn() without argument to start a check in, and subsequently with a boolean true or false after the job has successfully run or failed.