README

Acquia Coding Standards for PHP is a collection of PHP_CodeSniffer rules (sniffs) for Acquia coding standards for PHP projects, including Drupal extensions.

Notice: We have renamed our master branch to main. If you depend on dev-master, you'll need to switch to dev-main or an actual version like ^3.0.

Rules

Acquia Coding Standards for PHP includes a selection of sniffs from the following rulesets:

• Drupal Code Sniffer encapsulates Drupal coding standards and best practices for module development.
• PHP_CodeSniffer itself contains several broadly applicable rulesets.
• Slevomat Coding Standard provides functional (safety and behavior), cleaning (dead code), and formatting (consistent look) sniffs.

Rulesets

Rules are split into rulesets according to the project framework and audience:

• Projects targeting the Drupal community, e.g., Drupal modules, should adopt a Drupal ruleset. All others should adopt a (more generalized) PHP ruleset.
• Public projects, e.g., open-source Drupal modules, should adopt a non-strict ruleset to facilitate external collaboration. All others should adopt a more opinionated internal ruleset.

There are four permutations of these guidelines, leading to four rulesets to choose from:

• AcquiaDrupalMinimal is based on the Drupal coding standard and is intended for use on all public Drupal projects.
• AcquiaDrupalStrict is based on AcquiaDrupal and adds the more opinionated DrupalPractice standard. It is intended for use on all internal Drupal projects.
• AcquiaPHPMinimal is based on PSR-12 and is intended for use on all public non-Drupal projects.
• AcquiaPHPStrict is based on AcquiaPHP and adds additional, more opinionated standards. It is intended for use on all internal, non-Drupal projects.

Installation & usage

1. Add Acquia Coding Standards for PHP to your project via Composer:

   composer require --dev acquia/coding-standards

   If you want to add PHP cross-version compatibility checks, we suggest PHPCompatibility.

2. Inform PHP CodeSniffer of the location of the standard and its dependencies:

   • It is strongly recommended that you use a Composer plugin to handle this for you, e.g., DealerDirect/phpcodesniffer-composer-installer:

     composer config extra.phpcodesniffer-search-depth 4
     composer require --dev dealerdirect/phpcodesniffer-composer-installer

   • Alternatively, add a script to your composer.json to handle it:

     {
         "scripts": {
             "post-install-cmd": "@install-coding-standards",
             "post-update-cmd" : "@install-coding-standards",
             "install-coding-standards": "\"vendor/bin/phpcs\" --config-set installed_paths vendor/acquia/coding-standards/src/Standards,vendor/drupal/coder/coder_sniffer,vendor/slevomat/coding-standard"
         }
     }

3. Check code for standards compliance:

   ./vendor/bin/phpcs --standard=AcquiaDrupalStrict --extensions=php,module,inc,install,test,profile,theme,css,info,txt,md,yml path/to/code

   Automatically fix any standards violations possible:

   ./vendor/bin/phpcbf --standard=AcquiaDrupalStrict --extensions=php,module,inc,install,test,profile,theme,css,info,txt,md,yml path/to/code

   The --extensions argument must match the chosen code standard. For AcquiaPHP, use --extensions=php,inc,test,css,txt,md,yml.

4. Optionally create a default configuration file for your project so you don't have to provide the command-line arguments every time (i.e., below). Here's a working example: example/phpcs.xml.dist.

   ./vendor/bin/phpcs

   Modify phpcs.xml.dist to suit your project, especially to set the preferred code standard and matching extensions.

5. Optionally add code checking to your Git pre-commit hook to prevent committing code with violations. Since client-side Git hooks are not copied when a repository is cloned, you might like to use an automated solution like BrainMaestro/composer-git-hooks to manage them, for example: example/composer.json.

6. Optionally configure PHP Code Sniffer integration in PhpStorm or your IDE or code editor of choice. You can import example/PhpStormInspections.xml to set up default integration for new projects. When you open or create a new project for the first time, PhpStorm should automatically detect and set up PHPCS inspections based on these defaults. You will just need to uncheck the “installed standards paths” in the inspection settings for your project so that PhpStorm can find the Acquia Coding Standards.

Branches and supported release lines

The project currently maintains these long-lived branches:

• main for releases in the active 4.x line.
• develop for ongoing 4.x development. In Composer, this branch is aliased as 4.x-dev.
• support/3 for long-term support releases in the 3.x line. In Composer, this branch is aliased as 3.x-dev.

See CONTRIBUTING.md for pull request targeting guidance and RELEASING.md for maintainer release steps.

Contribution

Contributions are welcome! See CONTRIBUTING.md.

License

Copyright (C) 2019 Acquia, Inc.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.