PHPQA

Analyze PHP code with one command.

Requirements

• PHP >= 5.4.0
• xsl extension for HTML reports

Why?

Every analyzer has different arguments and options in different formats (no surprise in PHP world :). If you ever tried to get ignoring directories to work then you know what I mean. On the other hand CLI tools are cool because you can analyze any directory or file. Unfortunately Jenkins, Travis, Scrutiziner needs special configuration file. What if you want to analyze every bundle in your Symfony app? Will you create e.g. Jenkins project/task for each bundle?

• I want to analyze selected directory without complex configuration and creating extra files/tasks
• I don't care about format of ignored directories in phploc, phpmd, ...
• I don't want to update all projects when QA tool is updated or if I've found cool tool like PHPMetrics
• I don't want to analyze XML files → tool should be able to build html reports
• I want fast execution time → tools should run in parallel (thanks Robo)

Available tools

Tool	Description
phploc	Measure the size of a PHP project
phpcpd	Copy/Paste Detector (CPD) for PHP code
phpcs	Detect violations of a coding standard
pdepend	PHP adaptation of JDepend
phpmd	Scan PHP project for messy code
phpmetrics	Static analysis tool for PHP

Suggested tools

Newly added tools aren't preinstalled. You have to install relevant composer packages if you want to use them.

Tool	PHP	Supported since	Description
security-checker	>= 5.3	1.16	Check composer.lock for known security issues
php-cs-fixer	>= 5.3	1.12	Automatically detect and fix PHP coding standards issues
phpunit	>= 5.3	1.13	The PHP Unit Testing framework
phpstan	>= 7.0	1.9	Discover bugs in your code without running it
psalm	>= 5.6	1.14	A static analysis tool for finding errors in PHP applications
parallel-lint	>= 5.4	1.9	Check syntax of PHP files
MacFJA/phpqa-extensions	-	-	PHP Assumptions, Magic Number Detector, ...

Tip: use bin/suggested-tools.sh install for installing the tools.

Install

Clone + 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

Of course you can add dependency to require-dev section in your composer.json. But I wouldn't recommend it. In my experience one QA tool which analyzes N projects is better than N projects with N analyzers. It's up to you how many repositories you want to update when new version is released.

Symfony3 components

Symfony3 is supported since version 1.7. Install at least version ~3.0 of sebastian/phpcpd, otherwise you'll get error The helper "progress" is not defined.

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

Fake global installation in local project

Do you have problems with dependencies and you can't install phpqa globally? Install phpqa in subdirectory.

#!/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

Official docker image is https://hub.docker.com/r/zdenekdrahos/phpqa/. The image can be used at Gitlab CI. Beware that the image is as lean as possible. That can be a problem for running PHPUnit tests. In that case, you might miss PHP extensions for database etc (you can install phpqa in another php image).

docker run --rm -it zdenekdrahos/phpqa:v1.23.3 phpqa tools
# using a tool without phpqa
docker run --rm -it zdenekdrahos/phpqa:v1.23.3 phploc -v

There are also available images eko3alpha/docker-phpqa and sparkfabrik/docker-phpqa. phpqa is used as an entrypoint (I haven't been able to use these images at Gitlab CI).

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

Analyze

Command	Description
phpqa --help	Show help - available options, tools, default values, ...
phpqa --analyzedDirs ./ --buildDir ./build	Analyze current directory and save output to build directory
phpqa --analyzedDirs src,tests	Analyze source and test directory (phpmetrics analyzes only src)
phpqa --analyzedDir ./	Deprecated in v1.8 in favor of --analyzedDirs
phpqa --ignoredDirs build,vendor	Ignore directories
phpqa --ignoredFiles RoboFile.php	Ignore files
phpqa --tools phploc,phpcs	Run only selected tools
phpqa --tools phpmd:1,phpcs:0,phpcpd:0	Check number of errors and exit code. New in v1.6
phpqa --verbose	Show output from executed tools
phpqa --quiet	Show no output at all
phpqa --output cli	CLI output instead of creating files in --buildDir
phpqa --execution no-parallel	Don't use parallelism if --execution != parallel
phpqa --config ./my-config	Use custom configuration
phpqa --report	Build html reports
phpqa --report offline	Build html reports with bundled assets. New in v1.16
phpqa tools	Show versions of available tools

Tip: CLI options can be defined in .phpqa.yml

Output modes

Tool	--output file (default) - generated files	--output cli
phploc	phploc.xml	✓
phpcpd	phpcpd.xml	✓
phpcs	checkstyle.xml	full report
pdepend	pdepend-jdepend.xml, pdepend-summary.xml, pdepend-dependencies.xml, pdepend-jdepend.svg, pdepend-pyramid.svg	✗
phpmd	phpmd.xml	✓
phpmetrics	phpmetrics.html (v1), phpmetrics/index.html (v2), phpmetrics.xml	✓
php-cs-fixer	php-cs-fixer.html	✓
parallel-lint	parallel-lint.html	✓
phpstan	phpstan.html, phpstan-phpqa.neon	✓, phpstan-phpqa.neon
psalm	psalm.html, psalm.xml, psalm-phpqa.xml	✓, psalm-phpqa.xml

Exit code

phpqa can return non-zero exit code since version 1.6. It's optional feature that is by default turned off. You have to define number of allowed errors for phpcpd, phpcs, phpmd in --tools.

mode	Supported version	What is analyzed?
--output file	>= 1.6	Number of errors in XML files, or exit code for tools without XML
--output cli	>= 1.9	Exit code

Let's say your Travis CI or Circle CI build should fail when new error is introduced. Define number of allowed errors for each tools and watch the build:

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

Number of allowed errors can be also defined in .phpqa.yml.

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

File mode

Tip: override phpcs.ignoreWarnings if you want to count just errors without phpcs warnings.

CLI mode

Tip: use echo $? for displaying exit code.

Advanced configuration - .phpqa.yml

Provide CLI options from .phpqa.yml:

CLI option	.phpqa.yml
phpqa --analyzedDirs ./	phpqa.analyzedDirs: ./
phpqa --buildDir ./build	phpqa.buildDir: ./build
phpqa --ignoredDirs build,vendor	phpqa.ignoredDirs: build,vendor
phpqa --ignoredFiles RoboFile.php	phpqa.ignoredFiles: RoboFile.php
phpqa --tools phploc,phpcs:0	phpqa.tools: phploc,phpcs:0
phpqa --report	phpqa.report: true
phpqa --execution no-parallel	phpqa.execution: no-parallel
phpqa --output cli	phpqa.output: cli
phpqa --verbose	phpqa.verbose: true

Override tools' settings with .phpqa.yml:

Tool	Settings	Default Value	Your value
phpqa.extensions	PHP File extensions	php	Name of php file to parse, you can specify it like a string php,inc,modules or like a yaml array.
phpcs.standard	Coding standard	PSR2	Name of existing standard (PEAR, PHPCS, PSR1, PSR2, Squiz, Zend), or path to your coding standard. To specify multiple standards, you can use an array
phpcs.ignoreWarnings	If number of allowed errors is compared with warnings+errors, or just errors from checkstyle.xml	false	Boolean value
phpcs.reports	Report types	full report in cli mode, checkstyle in file mode	Predefined report types or custom reports
php-cs-fixer.rules	Coding standard rules	@PSR2	String value
php-cs-fixer.allowRiskyRules	Whether risky rules may run	false	Boolean value
php-cs-fixer.config	Load configuration from file	null	Path to .phpcs file
php-cs-fixer.isDryRun	If code is just analyzed or fixers are applied	true	Boolean value
phpmetrics.config	Configuration for phpmetrics v1	null	Path to .phpmetrics.yml file
phpmetrics.git	phpmetrics v2 analyses based on Git History	null	Boolean value or path to git binary
phpmetrics.junit	phpmetrics v2 evaluates metrics according to JUnit logs	null	Path to JUnit xml
phpmetrics.composer	phpmetrics v2 analyzes composer dependencies	null	Path to composer.json when the file is not included in analyzedDirs
pdepend.coverageReport	Load Clover style CodeCoverage report	null	Path to report produced by PHPUnit's --coverage-clover option
phpmd.standard	Ruleset	Edgedesign's standard	Path to ruleset. To specify multiple rule sets, you can use an array
phpcpd	Minimum number of lines/tokens for copy-paste detection	5 lines, 70 tokens
phpstan	Level, config file	Level 0, %currentWorkingDirectory%/phpstan.neon	Take a look at phpqa config in tests/.travis
phpunit.binary	Phpunit binary	phpqa's phpunit	Path to phpunit executable in your project, typically vendor/bin/phpunit
phpunit.config	PHPUnit configuration, analyzedDirs and ignoredDirs are not used, you have to specify test suites in XML file	null	Path to phpunit.xml file
phpunit.reports	Report types	no report	List of reports and formats, corresponds with CLI option, e.g. --log-junit is log: [junit] in .phpqa.yml
psalm.config	Psalm configuration, analyzedDirs and ignoredDirs are appended to projectFiles	Predefined config	Path to psalm.xml file
psalm.deadCode	Enable or not --find-dead-code option of psalm	false	Boolean value
psalm.threads	Set the number of process to use in parallel (option --threads of psalm) (Only if --execution == parallel for phpqa)	1	Number (>= 1)
psalm.showInfo	Display or not information (non-error) messages (option --show-info= of psalm)	true	Boolean value

.phpqa.yml is automatically detected in current working directory, but you can specify directory via option:

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

You don't have to specify full configuration. Missing or empty values are replaced with default values from our .phpqa.yml. Example of minimal config that defines only standard for CodeSniffer:

phpcs:
    standard: Zend

Tip: use PHP Coding Standard Generator for generating phpcs/phpmd standards.

You can specify multiple configurations directory (separated by ,). They are loaded in the order they are defined. This can be useful if you have a common configuration file that you want to use across multiple project but you still want to have per project configuration. Also, path inside configuration file are relative to where the configuration file is, so if you have a package that bundle a custom tool, the .phpqa.yml in the package can refers files within it.

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

HTML reports

If you don't have Jenkins or other CI server, then you can use HTML reports. HTML files are built when you add option --report. Take a look at report from phpqa.

# build html reports
phpqa --report

Custom templates

Define custom templates if you don't like default templates. You have to define path to xsl files in your .phpqa.yml:

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

Be aware that all paths are relative to .phpqa.yml. Don't copy-paste section report if you don't have custom templates!

Requirements

xsl extension must be installed and enabled for exporting HTML reports. Otherwise you'll get error PHP Fatal error: Class 'XSLTProcessor' not found.

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

Continuous integration

We use Jenkins-CI in Edgedesign. Below you can find examples of Phing, Robo and bash tasks.

Project with one directory

Typically in Symfony project you have project with src directory with all the code and tests. So you don't need ignore vendors, web directory etc.

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

Project with multiple directories (src, tests, ...)

When you analyze root directory of your project don't forget to ignore vendors and other non-code directories. Otherwise the analysis could take a very long time.

Since version 1.8 phpqa supports analyzing multiple directories. Except phpmetrics that analyzes only first directory. Analyze root directory and ignore other directories if you rely on phpmetrics report.

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 - artifacts + global installation

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 installation + composer cache + artifacts

stages:
  - test

test:
  stage: test
  image: zdenekdrahos/phpqa:v1.23.3
  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

Contributing

Contributions from others would be very much appreciated! Send pull request/issue. Thanks!

License

Copyright (c) 2015, 2016, 2017, 2018 Edgedesign.cz. MIT Licensed, see LICENSE for details.