locomotivemtl/charcoal-coding-standard

Charcoal Coding Standard

Charcoal Coding Standard

![License][badge-license] ![Build Status][badge-travis], _(*1)

The PHP_CodeSniffer ruleset to check that repositories are following the standards used by the Charcoal framework., _(*2)

Standards

The Charcoal Coding Standard extends and expands PSR-1 and PSR-2 ~~PSR-12~~., _(*3)

For a full reference of enforcements, please consult Charcoal/ruleset.xml., _(*4)

Installation

1. Project Installation

You can install the Charcoal Coding Standard as a Composer dependency of your project., _(*5)

1. Install the package via Composer:, _(*6)

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

2. Register the new standard with PHP_CodeSniffer:, _(*7)

   $ ./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., _(*8)

3. Create a phpcs.xml file at the base of your repository with the following content:, _(*9)

   <?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., _(*10)

   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:, _(*11)

   <rule ref="./vendor/locomotivemtl/charcoal-coding-standard/Charcoal/ruleset.xml" />
     

   Example: phpcs.xml.example., _(*12)

4. Add scripts to your composer.json:, _(*13)

   "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:, _(*14)

1. Install the package via Composer:, _(*15)

   $ composer global require locomotivemtl/charcoal-coding-standard
   

2. Register the new standard with PHP_CodeSniffer:, _(*16)

   $ 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., _(*17)

Usage

Sniffing

Depending on how you installed the Charcoal Coding Standard, you can do the following:, _(*18)

Detect violations of this standard with one of:, _(*19)

$ 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:, _(*20)

$ 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., _(*21)

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:, _(*22)

$ ./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., _(*23)

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:, _(*24)

$ 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., _(*25)

1. You can run the script from your project:, _(*26)

   $ ./vendor/locomotivemtl/charcoal-coding-standard/bin/phplint ./src ./tests
     

2. You can also symlink the script into your project's bin-dir:, _(*27)

   $ 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., _(*28)

Credits

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

License

Charcoal is licensed under the MIT license. See LICENSE for details., _(*29)