phpcsfixer-preset

---

This package allows you to use the same php-cs-fixer formatting rules across all of your projects without copy-and-pasting configuration files. There's also a quick setup script to automatically generate a configuration file for your 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: 7.3, 7.4, and 8.0.

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.dist 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/*');
    // ...

You can also use the standard PhpCsFixer\Finder class 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 will 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.dist

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 -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'd 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.

---

Finder Presets

BasicProjectFinder

• ignores VCS files
• ignores dot files
• 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

You may click on the name of each ruleset to see the specific rules it implements.

DefaultRuleset

• The default opinionated Ruleset provided by this package.

• View Rules

LaravelShiftRuleset

• Ruleset used by Laravel Shift.
• View Rules

PhpUnitRuleset

• Ruleset used by PHPUnit.
• View Rules

SpatieRuleset

• 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.dist 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.

If creating a new Ruleset package for your own use, follow the above example but use a namespace unique to your package.

---

Formatting Your Code

To format all files specified in the configuration, run:

vendor/bin/php-cs-fixer fix

To see which files will be formatted without making any changes, run:

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, bugfixes, suggestions, or improvements are welcomed. 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.