README

用一条命令分析PHP代码。

要求

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

为什么？

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

• 我想在不进行复杂配置和创建额外文件/任务的情况下分析所选目录
• 我不关心在 phploc、phpmd、... 中忽略目录的格式
• 我不想在QA工具更新或找到像 PHPMetrics 这样的酷工具时更新所有项目
• 我不想分析XML文件 → 工具应该能够构建 html 报告
• 我想有快速的执行时间 → 工具应该并行运行 (感谢 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，否则你会得到错误 未定义辅助程序 "progress"。

{
    "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.1-php7.2 phpqa tools
# using a tool without phpqa
docker run --rm -it ghcr.io/edgedesigncz/phpqa:v1.26.1-php7.2 phploc -v

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

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

还有其他可用的镜像eko3alpha/docker-phpqa和sparkfabrik/docker-phpqa。 phpqa用作入口点（我没有能够在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编码标准生成器生成phpcs/phpmd标准。

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

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

自定义二进制文件

每个工具都可以定义自定义二进制文件。如果您在处理依赖项时遇到问题，请使用phar或全局工具，例如。

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

通常，由于可以检测版本，因此首选 composer 安装。Phar 也可以工作，但可能有点棘手。如果某个工具具有包含 phar 的 composer 包（例如，vimeo/phar），请使用它而不是自定义二进制文件

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

可能性无限。您可以定义新的工具并运行它。例如，我喜欢在 phpmetrics v1 中“探索代码库”和在 v2 中使用 composer info。在 composer 中安装 phpmetrics v2，并使用 phar 的 v1 来避免 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 目录的项目，其中包含所有代码和测试。因此，您不需要忽略 vendors、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、...）的项目

当您分析项目的根目录时，请记住忽略 vendors 和其他非代码目录。否则，分析可能需要非常长的时间。

自版本 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.1-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.1-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

贡献

非常欢迎其他人的贡献！请发送 拉取请求/问题。谢谢！

许可

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