zvive/fixer

PHP CS Fixer w/ additional fixers based off of permafrost-dev/phpcsfixer-preset

Maintainers

Details

github.com/zvive/fixer

Source

Issues

Installs: 397

Dependents: 3

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 1

Open Issues: 0

v10.0 2023-02-24 22:27 UTC

Requires

Requires (Dev)

Suggests

MIT fdbcaca197ed4d352ba8729a57990fa0db2d87b6

  • Patrick Curl <patrickwcurl.woop@gmail.com>

laraveltoolingphp-cs-fixer

This package is auto-updated.

Last update: 2024-10-25 02:04:20 UTC

README



phpcsfixer-preset

version license downloads Run Tests Coverage Status


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.

zvive/fixer 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: 8.1.

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 zvive/fixer --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 Zvive\Fixer\Finders\LaravelProjectFinder;
use Zvive\Fixer\Rulesets\DefaultRuleset;
use Zvive\Fixer\SharedConfig;

$finder = LaravelProjectFinder::create(__DIR__);

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

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 Zvive\Fixer\Rulesets\SpatieRuleset;
use Zvive\Fixer\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 Zvive\Fixer\Finders\LaravelProjectFinder;
use Zvive\Fixer\Rulesets\DefaultRuleset;
use Zvive\Fixer\SharedConfig;

$finder = LaravelProjectFinder::create(__DIR__);

return SharedConfig::create($finder, new ZviveRuleset([
    // 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'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.

Automatic Formatting

If you would like to automatically apply php-cs-fixer formatting using Github Actions, see the automation with Github Actions documentation.

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

Rulesets

Default

  • The default opinionated Ruleset provided by this package.

  • View Rules

LaravelShift

PhpUnit

SpatieRuleset


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 Zvive\Fixer\Rulesets\DefaultRuleset class.

Creating Rulesets

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

Sample Ruleset:

<?php

namespace Zvive\Fixer\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 \Zvive\Fixer\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.