README

This tool enables you to integrate PHP_CodeSniffer into an existing project by automatically adding phpcs:ignore and phpcs:disable/phpcs:enable instructions throughout the codebase as a baseline. This allows you to make PHP_CodeSniffer pass without changing any source code, making it possible to use PHP_CodeSniffer in e.g. continuous integration pipelines or git hooks. This way, you can enforce that all new code adheres to your coding standard without touching the existing code.

Installation

Require the package with composer:

composer require --dev iodigital-com/php-code-sniffer-baseliner

It is also possible to install this package as a global composer dependency.

Usage

In order to add phpcs:ignore and phpcs:disable/phpcs:enable instructions throughout your project, run:

vendor/bin/phpcs-baseliner create-baseline

How does it work?

First, the tool runs vendor/bin/phpcs and captures the report. Based on the report output, it will add // phpcs:ignore instructions to the source code for each violation. It will only ignore the sniffs that actually are violated. In rare cases, adding these instructions could introduce new violations. Therefore, this process is repeated until no violations are reported by phpcs.

Example

Let's say we want to enforce declare(strict_types = 1); statements and native property type hints using PHP_CodeSniffer. The Slevomat Coding Standard has sniffs for this: SlevomatCodingStandard.TypeHints.DeclareStrictTypes and SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint. We install Slevomat Coding Standard and add the sniffs to our ruleset in phpcs.xml.

If we now run vendor/bin/phpcs-baseliner create-baseline in our project, it will add ignore instructions in all files not containing declare(strict_types = 1); statements or native property type declarations:

- <?php
+ <?php // phpcs:ignore SlevomatCodingStandard.TypeHints.DeclareStrictTypes -- baseline
  
  class Foo {
+     // phpcs:ignore SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint -- baseline
      private $bar;
  }

In some cases, it is not possible to insert a // phpcs:ignore instruction directly above the violated line (e.g. multi-line strings). In those cases, // phpcs:disable and // phpcs:enable instructions are added:

  <?php

  class Foo {
+     // phpcs:disable Generic.Files.LineLength.TooLong -- baseline  
      public const BAR = '
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas malesuada, lectus vitae vestibulum vulputate, mi morbi.';
+     // phpcs:enable Generic.Files.LineLength.TooLong -- baseline
  }

Features

Automatic indentation
Ignoring a group of multiple exclusions per line, e.g. // phpcs:ignore Generic.Files.LineLength.TooLong, Generic.Arrays.DisallowLongArraySyntax -- baseline
Merging new instructions with existing instructions
Messages of existing instructions are merged as wel: // phpcs:ignore Generic.Files.LineLength.TooLong, Generic.Arrays.DisallowLongArraySyntax -- existing message; baseline
Using phpcs:disable/phpcs:enable when inserting phpcs:ignore is not possible (i.e. for multi-line strings, including HEREDOCs and NOWDOCs)

Adding a star prefix when a violation is found within a comment block with stars, e.g.:

/*
 * phpcs:ignore Generic.Files.LineLength.TooLong
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas malesuada, lectus vitae vestibulum vulputate, mi morbi.
 */

All features are unit tested, see the AddBaselineProcessorTestDataProvider class for an extensive test data set.

Roadmap

Support processing files that do not start with <?php on the first line.
Support processing files that contain ?>.

Support ignoring violations on the first line of a file that end with a multi-line string, example:

<?php echo 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas malesuada, lectus vitae vestibulum vulputate, mi
morbi.';
?>

Support detection of and merging with older types of ignore instructions, such as @phpcsSuppress.

iodigital-com / php-code-sniffer-baseliner

Maintainers

Details