Installation

Back to the README

Install the package

composer require --dev festi-team/coding-standard

The package is published on the Festi Satis mirror every Festi composer.json already lists:

"repositories": [
    { "type": "composer", "url": "https://packages.festi.io/" }
]

Allow the Composer plugin. The standard registers itself with phpcs through a Composer plugin, and Composer refuses to run a plugin the root project has not allowed. Skipping this is the usual reason --standard=Festi "does not exist":

"config": {
    "allow-plugins": {
        "dealerdirect/phpcodesniffer-composer-installer": true
    }
}

Check the install: vendor/bin/phpcs -i must list Festi. There is no --config-set installed_paths step.

One install brings the whole toolchain: vendor/bin/phpcs, vendor/bin/phpmd, vendor/bin/phan, vendor/bin/festi-quality and vendor/bin/festi-phpcs-diff.

Requirement Constraint Note
PHP >=8.1 Phan 6 needs it. A project on 8.0 gets a Composer resolution error.
squizlabs/php_codesniffer ^3.13.6 \|\| ^4.0.2 The rules report identically on both majors. Releases before 3.13.6, and 4.0.0 and 4.0.1, have CVE-2026-67434 (a shell command in a file name, through the blame reports).
phan/phan ^6.0 Phan 5 crashes on current PHP versions.
phpmd/phpmd ^3.0 PHPMD 2.15.0 prints deprecation notices on PHP 8.4 and 8.5. PHPMD 3 has a different command line: see Usage.
pdepend/pdepend ^3.0 PHPMD uses PDepend to measure. PDepend 2.16.2 prints deprecation notices on PHP 8.4 and 8.5.
ext-ast suggested Without it, pass --allow-polyfill-parser to Phan: slower, but it works. Install it on runners that analyse large projects.

Set up Phan

Copy the template, edit the two lines marked EDIT, and run:

mkdir -p .phan
cp vendor/festi-team/coding-standard/phan/project-config.dist.php .phan/config.php
vendor/bin/phan --config-file .phan/config.php

The template merges the shared baseline with the project's own source directories and enables the Festi plugins. To write it by hand:

$base = require __DIR__.'/../vendor/festi-team/coding-standard/phan/config.php';

return array_merge($base, [
    // Keep the baseline's entry: the bundled stubs live inside the package,
    // and array_merge replaces this key rather than appending to it.
    'directory_list' => array_merge($base['directory_list'], [
        'src',
        'vendor/festi-team',
    ]),
]);

The same applies to plugins: array_merge replaces the key, so the project's list is the only place a plugin is enabled. Configuration covers tuning and baselines.

Set up SonarQube

Add sonar-project.properties to the project root:

sonar.projectKey=com.festi:<project>
sonar.projectName=festi/<project>

sonar.sources=./src/
sonar.tests=./tests
sonar.exclusions=tests/**,vendor/**

sonar.language=php

The scan itself runs in the project's pipeline. festi-quality only reads what a scan found. It needs SONAR_TOKEN, plus SONAR_HOST_URL unless the scan or the properties file (sonar.host.url) names the server. The sonar job of the project calls it after the scan: see GitLab CI.

Add the pipeline jobs

See GitLab CI.

Migrating an existing project

  1. composer require --dev festi-team/coding-standard and add the allow-plugins entry above.
  2. Delete the project's own copy of the standard: a .phan/ruleset.xml (a phpcs ruleset that lived in the Phan directory) or a vendored .phpcs/Festi directory.
  3. Set up Phan from the template, as above.
  4. Replace the project's style job with the include: from GitLab CI, and set FESTI_RUNNER_TAG.

Expect the full-tree run to go from green to a large report. It was green because the rules were not running. Do not try to fix the backlog in one merge request: gate on changed lines (festi-phpcs-diff), and work the backlog down as files are edited. Configuration describes the options.

One conflict to expect: festi-team/festi-framework-async pins phan/phan: 4.x, which does not resolve against this package's ^6.0. The pin has to be bumped as part of adoption.

Using it without Composer

Composer is the supported path. A git submodule works for the phpcs standard alone, for a tool that analyses code with no vendor/ install:

git submodule add [email protected]:FestiCore/php_festi_codingstandard.git \
    vendor/php_festi_codingstandard

vendor/bin/phpcs --standard=vendor/php_festi_codingstandard/Festi/ruleset.xml \
    --extensions=php --ignore='vendor/**' ./src

Pointing --standard at ruleset.xml needs no installed_paths for the Festi sniffs. The cognitive-complexity rule comes from slevomat/coding-standard, which phpcs must be told about when Composer did not register it: add --runtime-set installed_paths <path to slevomat>. festi-quality and festi-phpcs-diff need the Composer autoloader, so they are Composer-only.