README

phpcsfixer-preset

此包允许在所有项目中共享相同的 php-cs-fixer 格式化规则，而无需复制粘贴配置文件。还有一个快速设置脚本，可以自动为项目结构和首选格式化预设生成配置文件。

permafrost-dev/phpcsfixer-preset 提供了几个具有争议的 php-cs-fixer 配置选项，以及针对常见项目格式和用例预先配置的 Finder 类。

支持的 PHP 版本是 7.3、7.4、8.0、8.1 和 8.2。

此包的原始概念来源于 Tim Mcdonald 撰写的关于在项目中共享 php-cs-fixer 配置 的优秀文章。

安装

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

示例 .php-cs-fixer.dist.php 文件

此示例使用 Laravel 项目查找器和默认规则集

<?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());

可以将标准的 PhpCsFixer\Finder 选项链接到自定义的 Finder 类，以根据您的喜好对其进行自定义

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

可以使用标准 PhpCsFixer\Finder 类与任何规则集一起使用

<?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());

覆盖规则集规则

在创建 Ruleset 类时，您可以传递一个包含要添加或覆盖规则集默认规则的 php-cs-fixer 规则的数组。

<?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,
    ],
]));

快速设置

要为您的项目生成 php-cs-fixer 配置文件，请运行

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

参数： <type>

必需： 是

默认： 无默认值

可能的值

• custom
• project
• package
• laravel (laravel:project 的别名)
• laravel:project
• laravel:package

标志： --outfile (或 -o)

必需： 否

默认： .php-cs-fixer.dist.php

可能的值：任何有效的文件名

标志： --ruleset (或 -r)

必需： 否

默认： default

可能的值

• default
• laravel_shift
• php_unit
• spatie

标志： --force (或 -f)

必需： 否

默认： false

可能的值：无

效果：覆盖任何现有的配置文件

示例

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

关于 custom 类型的说明

将提示您输入 php-cs-fixer 要包含和排除的目录名称。生成的配置文件实现了 PhpCsFixer\Finder 类而不是预先配置的查找器类。

自动格式化

要使用 GitHub Actions 自动应用 php-cs-fixer 格式化，请参阅 使用 GitHub Actions 自动化 文档。

查找器预设

BasicProjectFinder

• 忽略 VCS 文件
• 忽略隐藏文件
• 包含 PHP 文件
• 排除 vendor/ 目录

LaravelProjectFinder

• 继承 BasicProjectFinder 预设
• 排除 *.blade.php 文件
• 排除所有在 bootstrap/、public/、resources/、storage/ 目录下的文件
• 包含在 app/、config/、database/、routes/、tests/ 目录下的 PHP 文件

LaravelPackageFinder

• 继承 BasicProjectFinder 预设
• 排除 *.blade.php 文件
• 排除所有在 resources/ 目录下的文件
• 包含在 src/、tests/、config/ 目录下的 PHP 文件

ComposerPackageFinder

• 继承 BasicProjectFinder 预设
• 包含在 src/、tests/ 目录下的 PHP 文件

规则集

默认

• 由本包提供的默认意见性规则集。
• 查看规则

LaravelShift

• 由 Laravel Shift 使用的规则集。
• 查看规则

PhpUnit

• 由 PHPUnit 使用的规则集。
• 查看规则

Spatie

• 由 Spatie 使用的规则集。
• 查看规则

使用方法

选择一个查找器预设或创建一个 \PhpCsFixer\Finder 的实例，并从 .php-cs-fixer.dist.php 文件返回 SharedConfig::create($finder)。

更新默认规则

更新 Permafrost\PhpCsFixerRules\Rulesets\DefaultRuleset 类中的 rules() 方法。

创建规则集

创建一个实现了 Permafrost\PhpCsFixerRules\Rulesets\Ruleset 接口的新类，从 rules() 方法返回你的规则。

示例规则集

<?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
    }
}

如果你要向本包添加新的规则集，必须在 \Permafrost\PhpCsFixerRules\Commands\GenerateConfigCommand@rulesets() 中注册该规则集，以便快速设置命令可以使用它。

在创建新的规则集包时，请遵循上面的示例，但使用唯一的包命名空间。

代码格式化

要格式化配置中指定的所有文件，请运行

vendor/bin/php-cs-fixer fix

要列出要处理的文件，而不进行任何更改

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

测试

此包使用 PHPUnit 进行单元测试。要运行测试套件，请运行

./vendor/bin/phpunit

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

欢迎对 Rulesets、Finders、错误修复、建议或改进的贡献。请为这些贡献中的任何一项打开一个适当标记的问题或拉取请求。

许可

MIT 许可证（MIT）。有关更多信息，请参阅 许可文件。