2x ConfigurationFile

The configuration file githooks.yml must be in root directory or in qa/ directory

./
  qa/
    githooks.yml # here or
  githooks.yml # here
  src/
  vendor/

• 1. Structure
  • 1.1. Options
    • 1.1.1. Execution
    • 1.1.2. Processes
  • 1.2. Tools
  • 1.3. Tools Configuration
  • 1.4. Phpstan
  • 1.5. Parallel-lint
  • 1.6. Phpcs and Phpcbf
  • 1.7. Phpmd
  • 1.8. Phpcpd
  • 1.9. Security-checker
• 2. Create Configuration File
• 3. Check Configuration File

1. Structure

This file have 3 diferent parts:

• Options (optional).
• Tools (mandatory).
• The configuration of the tools (the rest of the file). Mandatory for the tools setted in Tools tag.

1.1. Options

The Options tags may not be. In that case the default options will be established.

Options:
    execution: fast
    processes: 4

1.1.1. Execution

The execution flag marks how GitHooks will run:

• full (the default option): executes always all tools setted against all path setted for each tool. For example, you setted phpcs for run in src and app directories. The commit only contains modified files from database directory. Phpcs will check src and app directories even if no files in these directories have been modified.
• fast: this option runs the tools only against files modified by commit.
  • This option only affects the following tools: phpcs, phpmd, phpstan, and parallel-lint. The rest of the tools will run as the full option.
  • WARNING!!! You must set the excludes of the tools either in githooks.yml or in the configuration file of eath tool since this option overwrites the key paths of the tools so that they are executed only against the modified files.

1.1.2. Processes

The processes tag is used to run multiple tools in multiple processes. It can also be overridden by Cli. The default number of processes is 1.

1.2. Tools

It is an array with the name of the tools that GitHooks will run. See the README.md.

Attention: the order in which the tools are is the order in which they will be executed.

1.3. Tools Configuration

The rest of the file are tags with name of the tools. The mandatory tools are those described in the Tools label.

Some options are common to all tools while others are specific to each tool. The common options are:

• executablePath: where is the executable or binary for the tool. If not exists, GitHooks will interpret that the binary is in the global path.
• otherArguments: flags or arguments that are not covered in GitHooks. GitHooks supports a few arguments but obviously, every tool has many and it is not possible to support all of them.
• paths: the array of directories or files againts the tool will be runned. Security-checker is the only tool that does not have this option.

Other options are specific to each tool. For example, for set phpcs:

phpcs:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'
    otherArguments: '--report=summary --parallel=2'

There are no mandatory options for any tool. GitHooks support a subset of all possible arguments for each tool. More precise configuration is possible with each tool configuration file.

1.4. Phpstan

Argument	Description	Examples
executablePath	String. Path to executable. Default 'phpstan'	phpstan, 'vendor/bin/phpstan', 'path/to/phpstan'
paths	Array. Paths or files against the tool will be executed	['./src'], ['./src', './app/MiFile.php']
otherArguments	String. Flags or arguments that are not covered in GitHooks	'--no-progress', '--no-progress --ansi'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false
config	String. Path to configuration file	'phpstan.neon', 'path/to/phpstan.neon'
memory-limit	String. Set the php memory limit while phpstan is running	'1M', '2000M', '1G'
level	Integer. Default 0, max 9.	0, 1, 5, 8

1.5. Parallel-lint

Argument	Description	Examples
executablePath	String. Path to executable. Default 'parallel-lint'	parallel-lint, 'vendor/bin/parallel-lint', 'path/to/parallel-lint'
paths	Array. Paths or files against the tool will be executed	[src], [src, './app/MiFile.php']
otherArguments	String. Flags or arguments that are not covered in GitHooks	'--colors'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false
exclude	Array. Paths or files to exclude.	[vendor], [vendor, './app/MiFile.php']

1.6. Phpcs and Phpcbf

Argument	Description	Examples
executablePath	String. Path to executable. Default 'phpcs' or 'phpcbf'	phpcs, 'vendor/bin/phpcbf', 'path/to/phpcs'
paths	Array. Paths or files against the tool will be executed	[src], [src, './app/MiFile.php']
otherArguments	String. Flags or arguments that are not covered in GitHooks	'--report=summary', '--report=summary --parallel=2'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false
standard	String. Rules or configuration file with the rules.	'PSR12', 'Squizs', 'Generic', 'PEAR', 'myrules.xml'
ignore	Array. Paths or files to exclude.	[vendor], [vendor, './app/MiFile.php']
error-severity	Integer. Level of error to detect.	1, 5
warning-severity	Integer. Level of warning to detect.	5, 7, 9
usePhpcsConfiguration	Boolean. Grabs the phpcs setting. Default false. Only for phpcbf	true, false

The usePhpcsConfiguration option is used to simplify the configuration of phpcbf as it will normally use the same options as phpcs. Examples:

phpcs:
  phpcs:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'

phpcbf:
    usePhpcsConfiguration: true

Phpcbf is setted exactly like phpcs. The executablePath for phpcbf will be vendor/bin/phpcbf. usePhpcsConfiguration replace phpcs for phpcbf in the executablePath option.

phpcs:
  phpcs:
    executablePath: vendor/bin/phpcs
    paths: [src, tests]
    ignore: [vendor]
    standard: 'PSR12'
    error-severity: 5

phpcbf:
    usePhpcsConfiguration: true
    error-severity : 1
    paths: [src, tests, app]

Phpcbf takes the phpcs configuration but override the variables paths and error-severity.

1.7. Phpmd

Argument	Description	Examples
executablePath	String. Path to executable. Default 'phpmd'	phpmd, 'vendor/bin/phpmd', 'path/to/phpmd'
paths	Array. Paths or files against the tool will be executed	['./src'], ['./src', './app/MiFile.php']
otherArguments	String. Flags or arguments that are not covered in GitHooks	'--strict'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false
rules	String. Rules or configuration file with the rules.	'controversial,codesize', 'naming', 'myrules.xml'
exclude	Array. Paths or files to exclude.	['./vendor'], ['./vendor', './app/MiFile.php']

1.8. Phpcpd

Argument	Description	Examples
executablePath	String. Path to executable. Default 'phpcpd'	phpcpd, 'vendor/bin/phpcpd', 'path/to/phpcpd'
paths	Array. Paths or files against the tool will be executed	[src], [src, './app/MiFile.php']
exclude	Array. Paths or files to exclude.	[vendor], [vendor, './app/MiFile.php']
otherArguments	String. Flags or arguments that are not covered in GitHooks	'--min-lines=5'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false

1.9. Security-checker

Argument	Description	Examples
executablePath	String. Path to executable. Default 'local-php-security-checker'	local-php-security-checker, 'path/to/local-php-security-checker'
otherArguments	String. Flags or arguments that are not covered in GitHooks	'-format json'
ignoreErrorsOnExit	Boolean. Avoids error when the tool found trouble. Default false.	true, false

2. Create Configuration File

Before first run you must create and set the configuration file. For this you must run the command githooks conf:init. It copies a githooks.yml file template to the root of the project with all the options commented of each the tool.

Once created we can move it to qa/githookks.yml or leave it in the project root.

3. Check Configuration File

To make sure that when you finish configuring the githooks.yml, all the options are valid, you can launch the command githhooks conf:check:

GitHooks will be able to run as long as it doesn't have any errors. Warnings allow GitHooks to run but all configured tools may not run or some may work unexpectedly.