README

当多个程序员共同工作于一个大型项目时，会出现问题——每个程序员都有自己的代码编写风格和对程序不同部分实现的理解。由于每个人都在按照自己的意愿编写，其他开发者很难快速融入新的项目。

即使程序员试图遵循公司通用的代码编写规则（https://webtech.techart.ru/code-style-php/），仍然存在人为因素，并且必然会有规则被忽视的情况。

为了优化这个流程，创建了php-tooling软件包（https://packagist.org.cn/packages/techart/php-tooling），其中包含功能强大的代码格式化工具。代码格式化工具会分析项目代码，并显示不符合规则的地方的错误和警告。

代码格式化工具的结果如下

安装

php-tooling软件包应该存在于你的主供应商网站之外。可以使用以下命令进行安装：

vcomposer create-project techart/php-tooling

此命令将在当前路径下创建一个名为软件包的文件夹，并将其文件克隆到该文件夹中，同时自动执行 composer install。 （别忘了将此软件包的 vendor 文件夹添加到 .gitignore）。

如果php-tooling已经存在，则只需要使用 vcomposer install 收集 vendor 软件包。

安装路径

Bitrix

在Bitrix项目中，软件包需要安装到 local 文件夹中。

TAO3

在TAO3项目中，软件包需要安装到项目根目录。

使用

Bitrix

在Bitrix项目中，通常默认安装我们的软件包 bitrix.tao（https://packagist.org.cn/packages/techart/bitrix.tao）。此软件包具有特殊的 cli 命令。

vphp cli.php php_lint_run

此命令将从 www 文件夹启动代码分析过程。

有关 cli 命令的功能，请参阅此处： https://webtech.techart.ru/bitrix-tao/cli/。

TAO3

对于TAO3项目，存在特殊的 artisan 命令

vphp artisan php-lint:run

有关 artisan 命令的详细信息，请参阅 Laravel 的官方文档： https://laravel.net.cn/docs/9.x/artisan

其他项目

需要在 php-tooling 文件夹中执行以下命令

vphp ./vendor/bin/phpcs <Путь начала сканирования> --colors

直接在文件夹中调用命令的必要性是由于在其他位置调用时将使用标准的代码格式化规则。

代码格式化规则

php-tooling 文件夹中包含一个 phpcs.xml 文件。它是在基于 PSR12 规则（https://www.php-fig.org/psr/psr-12/）的基础上创建的，这可以说是扩展的 PSR2 规则，我们几乎遵循这些规则。在此文件中添加规则和例外情况。强烈不建议直接修改此文件（至少对于标准 Bitrix 和 TAO3 项目），它应该是公共的，因此如果需要添加某些例外或规则，应向上级报告，通常是团队领导。

例外情况

对于 Bitrix 项目，通常会在 .section.php 文件中看到声明数组但不在该文件中使用的文件。代码格式化工具会相应地指出这种情况。为了避免这种情况，存在例外功能：要忽略某行，请在该行上方写上以下内容

// phpcs:ignore

此注释将告知代码检查器忽略下一行。

要排除整个文件，可以使用以下命令

// phpcs:ignoreFile

写入文件开头。

这些命令仅适用于特殊情况。对于有争议的错误或情况，应在过程中讨论并补充文件规则。

在gitlab-ci中使用代码检查器

这部分正在开发中 目前可以创建如下格式的gitlab-ci任务

php_lint_test:
  stage: test
  variables:
    CODE_SNIFFER_PATH: <Путь до php-tooling>
  tags:
    - docker
    - php81 // Тег php-ранера, который используется на проекте
    - techart
  script:
    - |
      cd $CODE_SNIFFER_PATH && pwd
      composer install
      php ./vendor/bin/phpcs ../ --colors

如果代码检查器发现错误，发布过程将因错误而停止。

PHPUnit 测试

有关编写unit测试的详细文档请参阅此处： https://docs.phpunit.de/en/10.3/writing-tests-for-phpunit.html#asserting-return-values

用于运行 /tests/ 目录中所有测试的脚本：composer phpunit:run