README

⚠️ 此包不再维护。请参阅 Jubeki/laravel-code-style 以获取维护的分支。

此包为 Laravel 应用程序和包提供自动代码风格检查和格式化。您的代码将按照 Laravel 的代码风格指南进行格式化。

包添加了 php-cs-fixer 工具和社区维护的规则集到您的应用程序中。规则集是尽可能匹配 Laravel 框架本身使用的代码风格的最佳尝试。查看示例了解代码风格的外观。

如果您正在编写 Laravel 应用程序、包或教程，并且希望匹配框架的代码风格，您可能希望使用此包。

如果您想知道此包为什么存在，您可以阅读公告帖子。

安装

⚠️ 这些文档是为最新版本准备的。如果您使用的是旧版本，您可以在此处找到之前版本的相关文档。

使用 composer 安装此包。建议只将包要求用于开发。

composer require matt-allan/laravel-code-style --dev

服务提供者将使用包发现自动注册。

如果您不使用自动发现，则应将服务提供者添加到 config/app.php 中的 providers 数组中。

// existing providers...
MattAllan\LaravelCodeStyle\ServiceProvider::class,

一旦安装了包，您应该发布配置。

php artisan vendor:publish --provider="MattAllan\LaravelCodeStyle\ServiceProvider"

发布配置将在项目根目录添加一个 .php-cs-fixer.dist.php 配置文件。您可以根据需要自定义此文件。应将 .php-cs-fixer.dist.php 文件提交到版本控制系统中。

第一次运行修复器时，将在项目根目录的 .php_cs.cache 中写入一个缓存文件。您应该忽略此文件，以确保它不会添加到您的版本控制系统。

echo '.php_cs.cache' >> .gitignore

使用

安装包后，您可以使用 php-cs-fixer 命令检查和修复您的代码格式。该命令将在 Composer 的 vendor/bin 目录中可用。

修复

要自动修复您项目的代码风格，您可以使用 php-cs-fixer fix 命令。

vendor/bin/php-cs-fixer fix

这将自动修复您项目中的每个文件的代码风格。

默认情况下，仅显示每个修复文件的文件名。要查看每个更改的完整差异，请附加 --diff 标志。

vendor/bin/php-cs-fixer fix --diff

检查

如果您想检查格式而不实际更改任何文件，应使用带有--dry-run标志的fix命令。

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

在模拟运行模式下，任何违规都会导致命令返回非零退出代码。您可以使用此命令来使CI构建或git提交钩子失败。

Composer 脚本

为了使项目贡献者更容易检查和修复代码风格，建议将命令添加为composer 脚本。

以下示例允许任何人通过调用composer check-style来检查代码风格，并通过调用composer fix-style来修复代码风格。

{
    // ...
    "scripts": {
        "check-style": "php-cs-fixer fix --dry-run --diff",
        "fix-style": "php-cs-fixer fix"
    }
}

配置

默认配置作为.php-cs-fixer.dist.php发布在项目根目录中。您可以通过自定义此文件来更改选项，例如搜索路径或应用的修复。

路径

您可以通过对传递给MattAllan\LaravelCodeStyle\Config::setFinder方法的PhpCsFixer\Finder实例进行方法调用链来更改搜索PHP文件的路径。

例如，要搜索examples目录，您将附加->in('examples')

<?php

require __DIR__ . '/vendor/autoload.php';

return (new MattAllan\LaravelCodeStyle\Config())
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(app_path())
            // ...
            ->in('examples')
    )
    // ...

默认路径是为Laravel应用程序设置的。如果您正在编写一个包，则路径辅助函数将不可用，您需要根据需要更改路径，例如PhpCsFixer\Finder::create()->in(__DIR__)。

有关选项的完整列表，请参阅Symfony Finder 文档。

规则

默认情况下，仅启用@Laravel预设。此预设强制执行PSR-2标准以及几乎100其他规则，如按字母顺序排序use语句和强制多行数组中包含尾随逗号。

还有一个@Laravel:risky预设。该@Laravel:risky预设启用了可能会更改代码行为的规则。要启用风险规则，您需要添加预设并将isRiskyEnabled设置为true。

return (new MattAllan\LaravelCodeStyle\Config())
        ->setFinder(
            // ...
        )
        ->setRules([
            '@Laravel' => true,
            '@Laravel:risky' => true,
        ])
        ->setRiskyAllowed(true);

您可以从预设中覆盖特定规则。例如，您可以像这样禁用no_unused_imports规则

return (new MattAllan\LaravelCodeStyle\Config())
        ->setFinder(
            // ...
        )
        ->setRules([
            '@Laravel' => true,
            'no_unused_imports' => false,
        ]);

有关可用规则的完整列表，请参阅php-cs-fixer 文档。

持续集成

要自动修复当有人打开pull request或推送commit时的代码风格，请检查StyleCI。StyleCI编写了这个包所依赖的许多开源修复规则，并且StyleCI的Laravel预设是Laravel代码风格的官方定义。

编辑器支持

任何php-cs-fixer的编辑器插件都将正常工作。有关更多信息，请查看php-cs-fixer 读取文件。

工作原理

Laravel 并未发布官方的 php-cs-fixer 规则集。为了创建规则集，我们比较了 StyleCI 的预设和可用的 php-cs-fixer 规则。在某些情况下，StyleCI 使用的是已不再可用的规则。对于这些规则，我们必须挖掘 php-cs-fixer 的 git 历史记录，以确定哪个规则替代了已弃用的规则。

无法将您自己的预设添加到 php-cs-fixer 中。相反，通过扩展 PhpCsFixer\Config 来搜索我们的自定义预设，如果找到规则则合并它们。

为了确保规则保持同步，一个自动测试格式化整个 Laravel 框架并比较结果。如果现有的 Laravel 文件不符合我们的规则集，则构建失败。

版本发布

当 Laravel 更改代码风格时，将为该包创建一个新的主要版本。您需要编辑 composer.json 中的版本约束条件，以拉取更新的规则。如果您希望代码风格与 Laravel 的早期版本匹配，可以拉取此包的旧版本。

Laravel	代码风格
5.x	0.4.x
6.x-7.x	0.5.x
8.x	0.6.x

变更日志

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

测试

$ composer test

matt-allan / laravel-code-style

维护者

详情