README

一条命令分析PHP代码。

要求

• PHP >= 5.4.0
• xsl 扩展用于 HTML 报告

为什么？

每个分析器在不同的格式中都有不同的参数和选项 (在PHP世界中不足为奇 :)。如果您曾经尝试让忽略目录工作，那么您知道我的意思。另一方面，CLI工具很酷，因为您可以分析任何目录或文件。不幸的是，Jenkins，Travis，Scrutiziner需要特殊的配置文件。如果您想分析您Symfony应用程序中的每个包怎么办？您会为每个包创建Jenkins项目/任务吗？

• 我想在不进行复杂配置和创建额外文件/任务的情况下分析所选目录
• 我不关心在phploc、phpmd等中忽略目录的格式 ignored directories
• 我不想在QA工具更新或找到像PHPMetrics这样的酷工具时更新所有项目
• 我不想分析XML文件→工具应该能够构建 html reports
• 我想快速执行时间→工具应该并行运行 (感谢Robo)

可用的 工具

建议的工具

新添加的工具未预安装。如果您想使用它们，您必须安装相关的composer包。

提示：使用 bin/suggested-tools.sh install 安装工具。

安装

克隆 + composer

# install phpqa
git clone https://github.com/EdgedesignCZ/phpqa.git && cd phpqa && composer install --no-dev

# make phpqa globally accessible
## you can symlink binary
sudo ln -s /path-to-phpqa-repository/phpqa /usr/bin/phpqa
## or add this directory to your PATH in your ~/.bash_profile (or ~/.bashrc)
export PATH=~/path-to-phpqa-repository-from-pwd:$PATH

Composer

# global installation
composer global require edgedesign/phpqa --update-no-dev
# Make sure you have ~/.composer/vendor/bin/ in your PATH.

# local installation
composer require edgedesign/phpqa --dev

当然，您可以在您的 composer.json 中的 require-dev 部分添加依赖项。但我不会推荐这样做。在我的经验中，一个 分析N个项目的QA工具比N个项目使用N个分析器要好。您可以根据新版本发布时希望更新的仓库数量来决定。

Symfony3组件

Symfony3自版本1.7起支持。请安装至少版本 ~3.0 的 sebastian/phpcpd，否则您将收到错误 The helper "progress" is not defined.

{
    "require-dev": {
        "edgedesign/phpqa": ">=1.7",
        "sebastian/phpcpd": "~3.0"
    }
}

在本地项目中假全局安装

您有依赖项问题，不能全局安装phpqa吗？在子目录中安装phpqa。

#!/bin/sh

if [ ! -f qa/phpqa ];
then
    echo "installing phpqa"
    (git clone https://github.com/EdgedesignCZ/phpqa.git ./qa  && cd qa && composer install --no-dev)
fi

qa/phpqa

Docker

官方Docker镜像仓库是https://github.com/EdgedesignCZ/phpqa/pkgs/container/phpqa。镜像可以在Gitlab CI中使用。

docker run --rm -it ghcr.io/edgedesigncz/phpqa:v1.26.2-php7.2 phpqa tools
# using a tool without phpqa
docker run --rm -it ghcr.io/edgedesigncz/phpqa:v1.26.2-php7.2 phploc -v

请注意，图像尽可能精简。这可能会在运行PHPUnit测试时出现问题。在这种情况下，您可能需要不同的PHP版本、缺少数据库等PHP扩展。您可以在另一个php image中安装phpqa，或者构建自定义Docker镜像。

docker run --rm -it ghcr.io/edgedesigncz/phpqa:v1.26.2-php7.2 sh -c "php --version && composer --version && composer outdated --direct --all && phpqa tools"
docker run --rm -it ghcr.io/edgedesigncz/phpqa:v1.26.2-php8.1 sh -c "php --version && composer --version && composer outdated --direct --all && phpqa tools"

还有其他可用的镜像 eko3alpha/docker-phpqa 和 sparkfabrik/docker-phpqa。 phpqa 作为 entrypoint 使用（我在Gitlab CI + Windows可能需要不同的环境变量）。

docker run --rm -u $UID -v $PWD:/app eko3alpha/docker-phpqa --report --ignoredDirs vendor,build,migrations,test

提示： CLI选项可以在.phpqa.yml中定义

输出模式

退出代码

phpqa从版本1.6开始可以返回非零退出代码。这是一个可选功能，默认情况下是关闭的。您必须定义在--tools中允许的错误数phpcpd, phpcs, phpmd。

假设您的Travis CI或Circle CI构建在引入新错误时应该失败。为每个工具定义允许的错误数并监视构建

phpqa --report --tools phpcs:0,phpmd:0,phpcpd:0,parallel-lint:0,phpstan:0,phpmetrics,phploc,pdepend

允许的错误数也可以在.phpqa.yml中定义。

phpqa:
    # can be overriden by CLI: phpqa --tools phpcs:1
    tools:
        - phpcs:0

文件模式

提示：如果您只想计数错误而不想计数 phpcs 警告，则可以覆盖phpcs.ignoreWarnings。

CLI模式

提示：使用echo $?来显示退出代码。

高级配置 - .phpqa.yml

从.phpqa.yml提供CLI选项

文件

.phpqa.yml将在当前工作目录中自动检测，但您也可以通过选项指定目录

# use .phpqa.yml from defined directory
phpqa --config path-to-directory-with-config

您不需要指定完整的配置。缺失或空值将被替换为我们.phpqa.yml中的默认值。以下是一个仅定义CodeSniffer标准的最低配置示例

phpcs:
    standard: Zend

提示：使用PHP Coding Standard Generator生成 phpcs/phpmd 标准。

您可以为多个配置目录指定多个配置（以逗号分隔）。它们将按照定义的顺序加载。如果您有一个要在多个项目中使用的公共配置文件，但仍然希望每个项目都有自己的配置，这将很有用。此外，配置文件内的路径相对于配置文件的位置，因此如果您有一个捆绑自定义工具的包，该包中的.phpqa.yml可以引用其内的文件。

phpqa --config ~/phpqa/,my-config/,$(pwd)

自定义二进制

每个工具都可以定义自定义二进制。如果您有依赖项问题，请使用phar或全局工具，例如。

• 由于symfony组件或php版本无法安装某些内容
• 如果composer中安装了phpmetrics v1，则phpstan将无法工作（Hoa主文件（Core.php）只能包含一次。） -> 使用phar for phpmetrics

通常推荐使用composer安装，因为它可以检测版本。Phar也可以使用，但可能会有些棘手。如果某个工具的composer包中包含phar（例如vimeo/phar），请使用它而不是自定义的二进制文件

psalm:
    binary: /usr/local/bin/psalm.phar

可能性是无限的。你可以定义新的工具并运行它。例如，我喜欢在phpmetrics v1中探索代码库和在v2中使用composer info。在composer中安装phpmetrics v2，并使用phar来避免phpstan冲突

$ cat tests/.ci/.phpqa.yml
phpmetricsV1:
    binary: /usr/local/bin/phpmetrics.phar
tool:
    phpmetricsV1: Edge\QA\Tools\Analyzer\PhpMetrics

$ phpqa --config tests/.ci/ --tools phpmetricsV1,phpmetrics

覆盖工具设置

HTML报告

如果你没有Jenkins或其他CI服务器，则可以使用HTML报告。当你添加选项--report时，会构建HTML文件。请查看phpqa的报告。

# build html reports
phpqa --report

自定义模板

如果你不喜欢默认模板，请定义自定义模板。你必须在.phpqa.yml中定义xsl文件的路径

# use different template for PHPMD, use default for other tools
report:
    phpmd: my-templates/phpmd.xsl

请注意，所有路径都是相对于.phpqa.yml的。如果你没有自定义模板，请不要复制粘贴report部分！

要求

xsl扩展必须安装并启用，以便导出HTML报告。否则，你会得到错误PHP致命错误：找不到类'XSLTProcessor'。

# install xsl extension in Ubuntu
sudo apt-get update
sudo apt-get install php5-xsl
sudo service apache2 restart

持续集成

在Edgedesign，我们使用Jenkins-CI。以下是一些Phing、Robo和bash任务的示例。

单目录项目

通常在Symfony项目中，你有一个包含所有代码和测试的src目录。因此，你不需要忽略vendor、web目录等。

Phing - build.xml

<target name="ci-phpqa">
    <exec executable="phpqa" passthru="true">
        <arg value="--analyzedDirs=./src" />
        <arg value="--buildDir=./build/logs" />
        <arg value="--report" />
    </exec>
</target>

Robo - RoboFile.php

public function ciPhpqa()
{
    $this->taskExec('phpqa')
        ->option('analyzedDirs', './src')
        ->option('buildDir', './build/logs')
        ->option('report')
        ->run();
}

多目录项目（src、tests、...）

当你分析项目的根目录时，不要忘记忽略vendor和其他非代码目录。否则，分析可能需要很长时间。

从版本1.8开始，phpqa支持分析多个目录。除了仅分析第一个目录的phpmetrics之外。如果你依赖于phpmetrics报告，请分析根目录并忽略其他目录。

Phing - build.xml

<target name="ci-phpqa">
    <exec executable="phpqa" passthru="true">
        <arg value="--analyzedDirs=./" />
        <arg value="--buildDir=./build/logs" />
        <arg value="--ignoredDirs=app,bin,build,vendor,web" />
        <arg value="--ignoredFiles= " />
        <arg value="--verbose" />
        <arg value="--report" />
    </exec>
</target>

Robo - RoboFile.php

public function ciPhpqa()
{
    $this->taskExec('phpqa')
        ->option('verbose')
        ->option('report')
        ->option('analyzedDirs', './')
        ->option('buildDir', './build')
        ->option('ignoredDirs', 'build,bin,vendor')
        ->option('ignoredFiles', 'RoboFile.php,error-handling.php')
        ->run();
}

Bash

phpqa --verbose --report --analyzedDirs ./ --buildDir ./var/CI --ignoredDirs=bin,log,temp,var,vendor,www

Circle.ci - 程序件 + 全局安装

machine:
    php:
        version: 7.0.4

dependencies:
    cache_directories:
        - ~/.composer/cache
    post:
        - 'git clone https://github.com/EdgedesignCZ/phpqa.git ./qa && cd qa && composer install --no-dev'

test:
    override:
        - vendor/bin/phpunit --testdox-html ./var/tests/testdox.html --testdox-text ./var/tests/testdox.txt --log-junit $CIRCLE_TEST_REPORTS/phpunit/junit.xml
        - qa/phpqa --report --verbose --buildDir var/QA --ignoredDirs vendor --tools=phpcs:0,phpmd:0,phpcpd:0,phploc,pdepend,phpmetrics
    post:
        - cp -r ./var/QA $CIRCLE_ARTIFACTS
        - cp -r ./var/tests $CIRCLE_ARTIFACTS

Gitlab.ci - Docker安装 + composer缓存 + 程序件

stages:
  - test

test:
  stage: test
  image: ghcr.io/edgedesigncz/phpqa:v1.26.2-php7.2
  variables:
    BACKEND_QA: "*/backend/var/QA"
    BACKEND_CACHE: $CI_PROJECT_DIR/.composercache
  cache:
    paths:
    - $BACKEND_CACHE
  script:
    - 'export COMPOSER_CACHE_DIR=$BACKEND_CACHE'
    - 'composer install --ignore-platform-reqs --no-progress --no-suggest'
    - 'phpqa --report --tools phpcs:0,phpunit:0 --buildDir var/QA --analyzedDirs ./ --ignoredDirs var,vendor'
  artifacts:
    when: always
    paths:
    - $BACKEND_QA

Github actions - Docker安装 + composer缓存 + 程序件

name: QA

on: [push]

jobs:
  qa:
    container: ghcr.io/edgedesigncz/phpqa:v1.26.2-php8.1
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      # composer is not necessary, if you are not running phpunit/psalm/phpstan
      - name: Cache composer
        uses: actions/cache@v2
        with:
          path: |
            ~/.composer/cache
            vendor
          key: php-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: "php-composer-74"
      - name: Install dependencies
        run: |
          composer install --no-interaction --no-progress --ignore-platform-reqs;

      - name: phpqa
        run: phpqa --report --tools phpunit:0,phpcs:0,phpmd:0,psalm:0,phpstan:0 --buildDir build --analyzedDirs ./ --ignoredDirs build,vendor

      - name: Upload QA files
        uses: actions/upload-artifact@v2
        with:
          name: phpqa
          path: build

贡献

非常感谢其他人的贡献！请发送pull request/issue。谢谢！

许可

版权（c）2015 - 现在 Edgedesign.cz。MIT许可，有关详细信息请参阅LICENSE。