| 1 |
## About |
| 2 |
|
| 3 |
PHP_CodeSniffer is a set of two PHP scripts; the main `phpcs` script that tokenizes PHP, JavaScript and CSS files to |
| 4 |
detect violations of a defined coding standard, and a second `phpcbf` script to automatically correct coding standard |
| 5 |
violations. PHP_CodeSniffer is an essential development tool that ensures your code remains clean and consistent. |
| 6 |
|
| 7 |
[](https://travis-ci.org/squizlabs/PHP_CodeSniffer](https://travis-ci.org/squizlabs/PHP_CodeSniffer](https://travis-ci.org/squizlabs/PHP_CodeSniffer) [](http://squizlabs.github.io/PHP_CodeSniffer/analysis/squizlabs/PHP_CodeSniffer](http://squizlabs.github.io/PHP_CodeSniffer/analysis/squizlabs/PHP_CodeSniffer](http://squizlabs.github.io/PHP_CodeSniffer/analysis/squizlabs/PHP_CodeSniffer) [](https://gitter.im/squizlabs/PHP_CodeSniffer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge](https://gitter.im/squizlabs/PHP_CodeSniffer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge](https://gitter.im/squizlabs/PHP_CodeSniffer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 8 |
|
| 9 |
## Requirements |
| 10 |
|
| 11 |
PHP_CodeSniffer requires PHP version 5.4.0 or greater, although individual sniffs may have additional requirements such |
| 12 |
as external applications and scripts. See |
| 13 |
the [](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-OptionsConfiguration Options manual page](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options) for a |
| 14 |
list of these requirements. |
| 15 |
|
| 16 |
If you're using PHP_CodeSniffer as part of a team, or you're running it on |
| 17 |
a [](https://en.wikipedia.org/wiki/Continuous_integrationCI](https://en.wikipedia.org/wiki/Continuous_integration](https://en.wikipedia.org/wiki/Continuous_integration) server, you may want to configure your project's |
| 18 |
settings [](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-fileusing a configuration file](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file). |
| 19 |
|
| 20 |
## Installation |
| 21 |
|
| 22 |
The easiest way to get started with PHP_CodeSniffer is to download the Phar files for each of the commands: |
| 23 |
|
| 24 |
``` |
| 25 |
# Download using curl |
| 26 |
curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar |
| 27 |
curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar |
| 28 |
|
| 29 |
# Or download using wget |
| 30 |
wget https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar |
| 31 |
wget https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar |
| 32 |
|
| 33 |
# Then test the downloaded PHARs |
| 34 |
php phpcs.phar -h |
| 35 |
php phpcbf.phar -h |
| 36 |
``` |
| 37 |
|
| 38 |
### Composer |
| 39 |
|
| 40 |
If you use Composer, you can install PHP_CodeSniffer system-wide with the following command: |
| 41 |
|
| 42 |
composer global require "squizlabs/php_codesniffer=*" |
| 43 |
|
| 44 |
Make sure you have the composer bin dir in your PATH. The default value is `~/.composer/vendor/bin/`, but you can check |
| 45 |
the value that you need to use by running `composer global config bin-dir --absolute`. |
| 46 |
|
| 47 |
Or alternatively, include a dependency for `squizlabs/php_codesniffer` in your `composer.json` file. For example: |
| 48 |
|
| 49 |
```json |
| 50 |
{ |
| 51 |
"require-dev": { |
| 52 |
"squizlabs/php_codesniffer": "3.*" |
| 53 |
} |
| 54 |
} |
| 55 |
``` |
| 56 |
|
| 57 |
You will then be able to run PHP_CodeSniffer from the vendor bin directory: |
| 58 |
|
| 59 |
./vendor/bin/phpcs -h |
| 60 |
./vendor/bin/phpcbf -h |
| 61 |
|
| 62 |
### Phive |
| 63 |
|
| 64 |
If you use Phive, you can install PHP_CodeSniffer as a project tool using the following commands: |
| 65 |
|
| 66 |
phive install phpcs |
| 67 |
phive install phpcbf |
| 68 |
|
| 69 |
You will then be able to run PHP_CodeSniffer from the tools directory: |
| 70 |
|
| 71 |
./tools/phpcs -h |
| 72 |
./tools/phpcbf -h |
| 73 |
|
| 74 |
### PEAR |
| 75 |
|
| 76 |
If you use PEAR, you can install PHP_CodeSniffer using the PEAR installer. This will make the `phpcs` and `phpcbf` |
| 77 |
commands immediately available for use. To install PHP_CodeSniffer using the PEAR installer, first ensure you |
| 78 |
have [](http://pear.php.net/manual/en/installation.getting.phpinstalled PEAR](http://pear.php.net/manual/en/installation.getting.php](http://pear.php.net/manual/en/installation.getting.php) and then run the following command: |
| 79 |
|
| 80 |
pear install PHP_CodeSniffer |
| 81 |
|
| 82 |
### Git Clone |
| 83 |
|
| 84 |
You can also download the PHP_CodeSniffer source and run the `phpcs` and `phpcbf` commands directly from the Git clone: |
| 85 |
|
| 86 |
git clone https://github.com/squizlabs/PHP_CodeSniffer.git |
| 87 |
cd PHP_CodeSniffer |
| 88 |
php bin/phpcs -h |
| 89 |
php bin/phpcbf -h |
| 90 |
|
| 91 |
## Getting Started |
| 92 |
|
| 93 |
The default coding standard used by PHP_CodeSniffer is the PEAR coding standard. To check a file against the PEAR coding |
| 94 |
standard, simply specify the file's location: |
| 95 |
|
| 96 |
$ phpcs /path/to/code/myfile.php |
| 97 |
|
| 98 |
Or if you wish to check an entire directory you can specify the directory location instead of a file. |
| 99 |
|
| 100 |
$ phpcs /path/to/code-directory |
| 101 |
|
| 102 |
If you wish to check your code against the PSR-2 coding standard, use the `--standard` command line argument: |
| 103 |
|
| 104 |
$ phpcs --standard=PSR2 /path/to/code-directory |
| 105 |
|
| 106 |
If PHP_CodeSniffer finds any coding standard errors, a report will be shown after running the command. |
| 107 |
|
| 108 |
Full usage information and example reports are available on |
| 109 |
the [](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usageusage page](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage). |
| 110 |
|
| 111 |
## Documentation |
| 112 |
|
| 113 |
The documentation for PHP_CodeSniffer is available on |
| 114 |
the [](https://github.com/squizlabs/PHP_CodeSniffer/wikiGithub wiki](https://github.com/squizlabs/PHP_CodeSniffer/wiki](https://github.com/squizlabs/PHP_CodeSniffer/wiki). |
| 115 |
|
| 116 |
## Issues |
| 117 |
|
| 118 |
Bug reports and feature requests can be submitted on |
| 119 |
the [](https://github.com/squizlabs/PHP_CodeSniffer/issuesGithub Issue Tracker](https://github.com/squizlabs/PHP_CodeSniffer/issues](https://github.com/squizlabs/PHP_CodeSniffer/issues). |
| 120 |
|
| 121 |
## Contributing |
| 122 |
|
| 123 |
See [](CONTRIBUTING.mdCONTRIBUTING.md](CONTRIBUTING.md](CONTRIBUTING.md) for information. |
| 124 |
|
| 125 |
## Versioning |
| 126 |
|
| 127 |
PHP_CodeSniffer uses a `MAJOR.MINOR.PATCH` version number format. |
| 128 |
|
| 129 |
The `MAJOR` version is incremented when: |
| 130 |
|
| 131 |
- backwards-incompatible changes are made to how the `phpcs` or `phpcbf` commands are used, or |
| 132 |
- backwards-incompatible changes are made to the `ruleset.xml` format, or |
| 133 |
- backwards-incompatible changes are made to the API used by sniff developers, or |
| 134 |
- custom PHP_CodeSniffer token types are removed, or |
| 135 |
- existing sniffs are removed from PHP_CodeSniffer entirely |
| 136 |
|
| 137 |
The `MINOR` version is incremented when: |
| 138 |
|
| 139 |
- new backwards-compatible features are added to the `phpcs` and `phpcbf` commands, or |
| 140 |
- backwards-compatible changes are made to the `ruleset.xml` format, or |
| 141 |
- backwards-compatible changes are made to the API used by sniff developers, or |
| 142 |
- new sniffs are added to an included standard, or |
| 143 |
- existing sniffs are removed from an included standard |
| 144 |
|
| 145 |
> NOTE: Backwards-compatible changes to the API used by sniff developers will allow an existing sniff to continue |
| 146 |
> running without producing fatal errors but may not result in the sniff reporting the same errors as it did previously |
| 147 |
> without changes being required. |
| 148 |
|
| 149 |
The `PATCH` version is incremented when: |
| 150 |
|
| 151 |
- backwards-compatible bug fixes are made |
| 152 |
|
| 153 |
> NOTE: As PHP_CodeSniffer exists to report and fix issues, most bugs are the result of coding standard errors being |
| 154 |
> incorrectly reported or coding standard errors not being reported when they should be. This means that the messages |
| 155 |
> produced by PHP_CodeSniffer, and the fixes it makes, are likely to be different between PATCH versions. |
| 156 |
|
