Drupal Coding Standards (PHPCS) Setup and Usage Guide

Drupal Coding Standards (PHPCS) Setup and Usage Guide

Consistent code quality matters in every Drupal project, whether you are building an internal module, collaborating with a team, or preparing code for Drupal.org. One of the easiest ways to keep your codebase clean and predictable is to use PHP CodeSniffer with Drupal coding standards.

This guide walks through the full setup, from installing the required packages to running checks, fixing common issues, and building a workflow that helps keep your custom code in good shape.

Why PHPCS Matters in Drupal Projects

Drupal has its own coding standards, and following them is more than a formatting preference. Clean, standards-compliant code is easier to review, easier to maintain, and far more suitable for shared or public projects.

• It helps catch code style issues early.
• It improves readability across teams.
• It reduces manual review effort.
• It supports Drupal.org contribution expectations.

1. Install the Required Packages

From the root of your Drupal project, install the packages needed for Drupal coding standards and additional sniffs:

composer require --dev drupal/coder
composer require --dev slevomat/coding-standard

The Drupal Coder package provides the Drupal and DrupalPractice standards, while Slevomat adds extra useful rules that some standards depend on.

2. Configure PHPCS

After installation, tell PHPCS where those standards are located:

./vendor/bin/phpcs --config-set installed_paths vendor/drupal/coder/coder_sniffer,vendor/slevomat/coding-standard

Then verify the configuration:

./vendor/bin/phpcs -i

You should see something like:

3. Run a Coding Standards Check

To scan a custom module, point PHPCS at the module directory:

./vendor/bin/phpcs --standard=Drupal web/modules/custom/simple_404_logger

Replace the sample module path with your actual module name when running it in your project.

4. Auto-Fix What You Can

Many formatting and spacing issues can be fixed automatically with PHPCBF:

./vendor/bin/phpcbf --standard=Drupal web/modules/custom/simple_404_logger

This should usually be your first step after a scan. It saves time and leaves only the manual fixes for you to review.

5. Understand the Output

PHPCS generally reports two levels of findings:

• ERROR – something that should be fixed.
• WARNING – a recommendation or improvement.

Typical examples include missing doc comments, spacing problems, indentation errors, long lines, or import-related issues.

6. What to Fix First

When a scan returns a long report, start with the most common structural issues:

• Missing docblocks
• Incorrect indentation
• Naming convention violations
• Unused imports
• Spacing and formatting problems

Cleaning these first usually removes a large part of the report and makes the remaining issues easier to handle.

7. Common Issues and Fixes

Missing sniff errors

If you see a message like this:

Referenced sniff "SlevomatCodingStandard..." does not exist

Install the missing package:

composer require --dev slevomat/coding-standard

PHPCS not found

If your terminal says:

phpcs: command not found

Run the local vendor binary instead:

./vendor/bin/phpcs

Wrong module path

Make sure the target path is correct, for example:

web/modules/custom/your_module_name

8. Best Practices

• Run PHPCS before every release.
• Use PHPCBF first to auto-fix simple issues.
• Review and fix the remaining findings manually.
• Keep your custom code aligned with Drupal standards throughout development, not only before release.

9. Quick Commands Reference

composer require --dev drupal/coder
composer require --dev slevomat/coding-standard

./vendor/bin/phpcs --config-set installed_paths vendor/drupal/coder/coder_sniffer,vendor/slevomat/coding-standard

./vendor/bin/phpcs --standard=Drupal web/modules/custom/simple_404_logger

./vendor/bin/phpcbf --standard=Drupal web/modules/custom/simple_404_logger

Conclusion

Using PHPCS with Drupal coding standards helps keep your modules consistent, easier to maintain, and better prepared for team collaboration or public contribution. It also reduces the amount of avoidable code review feedback by catching formatting and standards issues early.

If you are working with custom Drupal development regularly, adding PHPCS to your workflow is a practical step that improves both code quality and release readiness.