permafrost-dev/phpcsfixer-preset

shared php-cs-fixer rules & finders preset

2.0.1 2022-02-12 00:17 UTC

Requires

• php: ^7.3||^8.0
• ext-json: *
• symfony/console: ^5.2|^6.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpunit/phpunit: ^9.5

MIT

README

phpcsfixer-preset

This package allows sharing identical php-cs-fixer formatting rules across all of your projects without copy-and-pasting configuration files. There is also a quick setup script to automatically generate a configuration file for the project structure and preferred formatting preset.

permafrost-dev/phpcsfixer-preset provides several opinionated php-cs-fixer configuration choices as well as pre-configured Finder classes for common project formats and use cases.

Supported PHP versions are 7.3, 7.4, 8.0, 8.1, and 8.2.

The original concept for this package came from this excellent article on sharing php-cs-fixer configurations across projects written by Tim Mcdonald.

Installation

composer require permafrost-dev/phpcsfixer-preset --dev

Example .php-cs-fixer.dist.php files

This example uses the Laravel project finder and the Default Ruleset:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Permafrost\PhpCsFixerRules\Finders\LaravelProjectFinder;
use Permafrost\PhpCsFixerRules\Rulesets\DefaultRuleset;
use Permafrost\PhpCsFixerRules\SharedConfig;

$finder = LaravelProjectFinder::create(__DIR__);

return SharedConfig::create($finder, new DefaultRuleset());

Standard PhpCsFixer\Finder options can be chained onto the custom Finder class to customize it to your preferences:

    // ...
    $finder = LaravelProjectFinder::create(__DIR__)
        ->in([__DIR__ . '/custom-src-dir'])
        ->notName('*.ignored.php')
        ->notPath('another-custom-dir/cache/*');
    // ...

The standard PhpCsFixer\Finder class can be used along with any of the Rulesets:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use PhpCsFixer\Finder;
use Permafrost\PhpCsFixerRules\Rulesets\SpatieRuleset;
use Permafrost\PhpCsFixerRules\SharedConfig;

$finder = Finder::create()
    ->ignoreVCS(true)
    ->ignoreDotFiles(true)
    ->name('*.php')
    ->in([
        __DIR__ . '/src',
        __DIR__ . '/tests',
    ])
    ->exclude(__DIR__ . '/vendor');

return SharedConfig::create($finder, new SpatieRuleset());

Overriding Ruleset Rules

When creating a Ruleset class, you may pass an array of php-cs-fixer rules that add or override the Ruleset's default rules.

<?php

require_once(__DIR__.'/vendor/autoload.php');

use Permafrost\PhpCsFixerRules\Finders\LaravelProjectFinder;
use Permafrost\PhpCsFixerRules\Rulesets\DefaultRuleset;
use Permafrost\PhpCsFixerRules\SharedConfig;

$finder = LaravelProjectFinder::create(__DIR__);

return SharedConfig::create($finder, new DefaultRuleset([
    // existing rules can be overridden:
    'no_break_comment' => true,
    'no_closing_tag' => false,
    // new rules can be added:
    'a_new_option' => [
        'some_sub_option' => 12,
    ],
]));

Quick Setup

To generate a php-cs-fixer configuration file for your project, run:

vendor/bin/pf-create-cs-config <type> [-o|--outfile=filename] [-r|--ruleset=name] [-f|--force]

Parameter: <type>

Required: yes

Default: no default

Possible values:

• custom
• project
• package
• laravel (alias for laravel:project)
• laravel:project
• laravel:package

Flag: --outfile (or -o)

Required: no

Default: .php-cs-fixer.dist.php

Possible values: any valid filename

Flag: --ruleset (or -r)

Required: no

Default: default

Possible values:

• default
• laravel_shift
• php_unit
• spatie

Flag: --force (or -f)

Required: no

Default: false

Possible values: none

Effect: overwrites any existing configuration file

Examples:

vendor/bin/pf-create-cs-config laravel:package

vendor/bin/pf-create-cs-config package -f

vendor/bin/pf-create-cs-config laravel -o .php-cs-fixer.php -r spatie

vendor/bin/pf-create-cs-config project --ruleset=laravel_shift

vendor/bin/pf-create-cs-config custom --outfile=.my-config

Note on the custom type:

The custom type will prompt you to enter the directory names you would like php-cs-fixer to include and exclude. The generated configuration file implements the PhpCsFixer\Finder class instead of one of the preconfigured finder classes.

Automatic Formatting

To apply php-cs-fixer formatting using Github Actions automatically, see the automation with Github Actions documentation.

Finder Presets

BasicProjectFinder

• ignores VCS files
• ignores dotfiles
• includes PHP files
• excludes vendor/ directory

LaravelProjectFinder

• inherits BasicProjectFinder presets
• excludes *.blade.php files
• excludes all files in bootstrap/, public/, resources/, storage/
• includes PHP files in app/, config/, database/, routes/, tests/

LaravelPackageFinder

• inherits BasicProjectFinder presets
• excludes *.blade.php files
• excludes all files in resources/
• includes PHP files in src/, tests/, config/

ComposerPackageFinder

• inherits BasicProjectFinder presets
• includes PHP files in src/, tests/

Rulesets

Default

• Default opinionated Ruleset provided by this package.
• View Rules

LaravelShift

• Ruleset used by Laravel Shift.
• View Rules

PhpUnit

• Ruleset used by PHPUnit.
• View Rules

Spatie

• Ruleset used by Spatie.
• View Rules

Usage

Select a Finder preset or create an instance of \PhpCsFixer\Finder and return SharedConfig::create($finder) from the .php-cs-fixer.dist.php file.

Updating Default Rules

Update the rules() method in the Permafrost\PhpCsFixerRules\Rulesets\DefaultRuleset class.

Creating Rulesets

Create a class that implements the Permafrost\PhpCsFixerRules\Rulesets\Ruleset interface, returning your rules from the rules() method.

Sample Ruleset:

<?php

namespace Permafrost\PhpCsFixerRules\Rulesets;

class MyCustomRulesRuleset implements RuleSet
{
    public function allowRisky(): bool
    {
        return true; //this tells php-cs-fixer whether or not to permit "risky" rules.
    }

    public static function name(): string
    {
        return 'my_custom_rules'; //the name should omit 'ruleset' from the end.
    }

    /**
     * @return array
     */
    public function rules(): array
    {
        return array_merge([
            '@PSR2' => true,
            // additional php-cs-fixer rules
        ], $this->additional); //it's important that the additional rules property is merged
    }
}

If adding a new Ruleset to this package, the Ruleset must be registered in \Permafrost\PhpCsFixerRules\Commands\GenerateConfigCommand@rulesets() to allow the quick setup command to use it.

When creating a new Ruleset package, follow the above example but use a namespace unique to the package.

Code Formatting

To format all files specified in the configuration, run:

vendor/bin/php-cs-fixer fix

To list the files to be processed without making any changes:

vendor/bin/php-cs-fixer fix --dry-run

Testing

This package uses PHPUnit for unit tests. To run the test suite, run:

./vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributions

Contributions of Rulesets, Finders, bug fixes, suggestions, or improvements are welcome. Please open an appropriately labeled issue or pull request for any of these.

License

The MIT License (MIT). Please see License File for more information.