README

It's simple baseline for PHP CS Fixer.

Pros:

• It helps to start using of PHP CS Fixer without preparing of all project. Case you don't need to fix them all at the beginning. Only new & changed on each iteration.
• It may speed up pipelines on CI for big projects.

Base project has requires for it but not implemented yet: PHP-CS-Fixer/PHP-CS-Fixer#6451

So, it's some work around till baseline will be implemented in the PHP CS Fixer.

Compatibility

This package requires friendsofphp/php-cs-fixer: ^3.0 (tested with 3.0.x and 3.95.x).

When PHP CS Fixer 3.95 is installed, Composer resolves Symfony 5.4 or newer. Projects on PHP CS Fixer 3.0.x can still use Symfony 4.4.

Installation

There are few ways of installation:

1. Phive
2. Composer
3. Composer bin plugin
4. Downloading of PHAR directly

Phive

You can install this package with Phive. It permits you to install package by one console command without extending dependencies in your composer-files.

phive install php-cs-fixer-baseline

Sometimes you may need to update database of package-aliases of PHIVE. See issue #3 So, just call console command for it:

phive update-repository-list

To upgrade this package use the following command:

phive update php-cs-fixer-baseline

Composer

You can install this package with Composer:

composer require --dev aeliot/php-cs-fixer-baseline

Composer bin plugin

You can install this package in an isolated vendor-bin namespace with bamarni/composer-bin-plugin. It helps when PHP CS Fixer dependencies conflict with your project vendors.

1. Enable the plugin in composer.json:

   {
       "config": {
           "allow-plugins": {
               "bamarni/composer-bin-plugin": true
           }
       }
   }

2. Install the plugin:

   composer require --dev bamarni/composer-bin-plugin

3. Install this package into a bin namespace:

   composer bin pcsf-baseline require --dev aeliot/php-cs-fixer-baseline

4. Use the CLI as usual:

   vendor/bin/pcsf-baseline

When bin-links is disabled, run the binary from vendor-bin/pcsf-baseline/vendor/bin/pcsf-baseline or add a Composer script alias.

Because PHP CS Fixer loads your project config in a separate process, require the bin autoloader in .php-cs-fixer.dist.php before using FilterFactory:

require_once __DIR__ . '/vendor-bin/pcsf-baseline/vendor/autoload.php';

Add /vendor-bin/**/vendor/ to .gitignore and consider extra.bamarni-bin.forward-command = true so composer install also installs bin namespaces.

Downloading of PHAR directly

Download PHAR directly to root directory of the project or in another place as you wish.

# Do adjust the URL if you need a release other than the latest
wget -O pcsf-baseline.phar "https://github.com/Aeliot-Tm/php-cs-fixer-baseline/releases/latest/download/pcsf-baseline.phar"
wget -O pcsf-baseline.phar.asc "https://github.com/Aeliot-Tm/php-cs-fixer-baseline/releases/latest/download/pcsf-baseline.phar.asc"

# Check that the signature matches
gpg --verify pcsf-baseline.phar.asc pcsf-baseline.phar

# Check the issuer (the ID can also be found from the previous command)
gpg --keyserver hkps://keys.openpgp.org --recv-keys 9D0DD6FCB92C84688B777DF59204DEE8CAE9C22C

rm pcsf-baseline.phar.asc
chmod +x pcsf-baseline.phar

Configuration

1. Extract Finder from the config of PHP CS Fixer to the separate file. It expects .php-cs-fixer-finder.php at the root of the project.

2. Add filtering of files detected by Finder.

   use Aeliot\PhpCsFixerBaseline\Service\FilterFactory;
   
   $finder->filter((new FilterFactory())->createFilter(__DIR__ . '/.php-cs-fixer-baseline.json', $config));

   Filter options (optional):

   use Aeliot\PhpCsFixerBaseline\Dto\FilterOptions;
   use Aeliot\PhpCsFixerBaseline\Service\FilterFactory;
   
   $finder->filter((new FilterFactory())->createFilter(
       __DIR__ . '/.php-cs-fixer-baseline.json',
       $config,
       new FilterOptions(
           mode: FilterFactory::MODE_MENTIONED,
           workdir: '/path/to/project',
       ),
   ));

   Mode	Description
   by_hash (default)	Skip files from baseline only when their content hash matches
   mentioned	Skip all files listed in baseline, even if they were modified

3. Autoload classes from PHAR (optional). If you use this project as PHAR file, you need to require autoloader of it to use provided filter. Do it in the main config file of PHP CS Fixer (.php-cs-fixer.dist.php)

   Phar::loadPhar('/path/to/pcsf-baseline.phar', 'pcsf-baseline.phar');
   require_once 'phar://pcsf-baseline.phar/vendor/autoload.php';

Using

Commands

1. Generate baseline. Just call script without options when all config files uses default names.
   • Call PHAR

     php pcsf-baseline.phar

   • Or call script installed via Composer:

     vendor/bin/pcsf-baseline

   See options below. You can see how it is configured in this project.
2. After fixing files with PHP CS Fixer, update their hash in baseline without regenerating it entirely:

   vendor/bin/pcsf-baseline update src/Foo.php src/Bar.php

   The baseline file must already exist. Only files already listed in baseline are updated; config_hash is not recalculated.
3. Use PHP CS Fixer as usual. All files mentioned in the baseline will be scip till they are not changed.

This script store relative paths to files in baseline file by default. It is useful when baseline used in different environments.

Options of generate command

Options baseline, config, finder can be absolute or related or omitted at all. In the last case it expects that files are in the root directory of project.

You can use option workdir to customize path to working directory. Otherwise, directory where the script called is used. The same with the filter for PHP CS Fixer. You may customize working directory by third option for filter factory.

Pass option absolute when you want to force saving of absolute paths to files of your project in baseline. It cannot be used with option workdir.

Use option invalid-only to generate a baseline only for files that currently violate PHP CS Fixer rules. This is useful when you want to adopt a baseline gradually: compliant files are not added, so PHP CS Fixer will still check them. The command always overwrites the whole baseline file. If every file is already compliant, the result is an empty baseline (Ok, 0 files added to baseline). Detection runs php-cs-fixer check via CLI (vendor/bin/php-cs-fixer by default). Override the binary path with the PHP_CS_FIXER_BINARY environment variable if needed.

Options of update command

File paths are passed as arguments (one or more):

vendor/bin/pcsf-baseline update src/Service/Foo.php src/Service/Bar.php

Restrictions for using of relative paths

1. Option workdir MUST be absolute. You cannot use "double dots" in it.
2. Used function realpath() for normalisation of paths of files returned by Finder. For proper cutting of workdir out of file path to make it relative. It may return unexpected result based on current user permissions. Look for restrictions of this function in official documentation of PHP.
3. When the function realpath() returns an empty result or path of file returned by Finder is not from working directory then path stored "as is".