README

The PHP_CodeSniffer ruleset to check that repositories are following the standards used by the Charcoal framework.

Standards

The Charcoal Coding Standard extends and expands PSR-1 and PSR-2 ~~PSR-12~~.

For a full reference of enforcements, please consult Charcoal/ruleset.xml.

Installation

1. Project Installation

You can install the Charcoal Coding Standard as a Composer dependency of your project.

Install the package via Composer:

$ composer require --dev locomotivemtl/charcoal-coding-standard

Register the new standard with PHP_CodeSniffer:
```
$ ./vendor/bin/phpcs --config-set installed_paths ./vendor/locomotivemtl/charcoal-coding-standard
```
The second command registers the standard with phpcs. Ensure existing values of the installed_paths option are not overwritten.
Create a phpcs.xml file at the base of your repository with the following content:
```
<?xml version="1.0"?>
<ruleset name="Charcoal Package">
    <rule ref="Charcoal" />
</ruleset>
```
You can include or exclude sniffs from this file. For a reference of customizations, consult the PHP_CodeSniffer annotated ruleset.
Note: If you did not register the Charcoal Coding Standard with PHP_CodeSniffer, you can reference the standard using its path instead of its name:
```
<rule ref="./vendor/locomotivemtl/charcoal-coding-standard/Charcoal/ruleset.xml" />
```
Example: phpcs.xml.example.

Add scripts to your composer.json:

"scripts": {
    "cs-check": "phpcs --colors -p ./src ./tests",
    "cs-fix": "phpcbf --colors ./src ./tests"
}

2. Global Installation

You can also install the Charcoal Coding Standard system-wide:

Install the package via Composer:

$ composer global require locomotivemtl/charcoal-coding-standard

Register the new standard with PHP_CodeSniffer:
```
$ phpcs --config-set installed_paths ~/.composer/vendor/locomotivemtl/charcoal-coding-standard
```
The second command registers the standard with phpcs. Ensure existing values of the installed_paths option are not overwritten.

Usage

Sniffing

Depending on how you installed the Charcoal Coding Standard, you can do the following:

Detect violations of this standard with one of:

$ phpcs --standard=Charcoal /path/to/some/file/to/sniff.php
$ ./vendor/bin/phpcs --standard=Charcoal /path/to/some/file/to/sniff.php
$ composer cs-check

Automatically fix violations of this standard with:

$ phpcbf --standard=Charcoal /path/to/some/file/to/sniff.php
$ ./vendor/bin/phpcbf --standard=Charcoal /path/to/some/file/to/sniff.php
$ composer cs-fix

For further usage options, see the CLI documentation.

Note: If you did not register the Charcoal Coding Standard with PHP_CodeSniffer, you can reference the standard using its path instead of its name:
$ ./vendor/bin/phpcs --standard=./vendor/locomotivemtl/charcoal-coding-standard /path/to/code

Linting

The Charcoal Coding Standard provides a simple but convenient bash script wrapper around php -l to recursively perform syntax checks on PHP files with several processes at once.

Usage:
  phplint [options] [<path>]...

Arguments:
  path            One or more paths to files or directories to search for PHP files.
                  Defaults to ./src and ./tests.

Options:
  -h, --help      Display this help message and exit.
  -V, --version   Display version information and exit.

Example:

$ phplint src/Http/Controllers/ src/Providers/RouteServiceProvider.php

Note: The script is not part of the composer.json; it is not added to the given project when the package is installed. The script must be called from the vendor package or you must manually symlink it into your bin-dir.
You can run the script from your project:
$ ./vendor/locomotivemtl/charcoal-coding-standard/bin/phplint ./src ./tests
You can also symlink the script into your project's bin-dir:
$ cd $(composer config bin-dir)
$ ln -s ../locomotivemtl/charcoal-coding-standard/bin/phplint ./phplint
Check out overtrue/phplint, a more advanced and configurable tool for linting PHP files.

Credits

Chauncey McAskill chauncey@locomotive.ca
Mathieu Ducharme mat@locomotive.ca

License

Charcoal is licensed under the MIT license. See LICENSE for details.

locomotivemtl / charcoal-coding-standard

Maintainers

Details