PHPCS (PHP CodeSniffer)

Overview

This WordPress theme template includes PHP CodeSniffer (PHPCS) as a development dependency to ensure code quality and adherence to WordPress coding standards. PHPCS is a tool that detects violations of coding standards and can automatically fix many common issues.

What is PHPCS?

PHP CodeSniffer is a set of two PHP scripts:

phpcs: Detects violations of a defined coding standard
phpcbf: Automatically corrects coding standard violations

It helps maintain consistent code style, improves readability, and catches potential issues before they reach production.

Installation & Setup

Dependencies

PHPCS is automatically installed via Composer with the following packages (defined in composer.json):

{
  "require-dev": {
    "squizlabs/php_codesniffer": "^3.10",
    "wp-coding-standards/wpcs": "^3.1",
    "dealerdirect/phpcodesniffer-composer-installer": "^1.0"
  }
}

squizlabs/php_codesniffer: The core PHPCS tool
wp-coding-standards/wpcs: WordPress-specific coding standards
dealerdirect/phpcodesniffer-composer-installer: Automatically installs coding standards

Configuration File

The PHPCS configuration is defined in .phpcs.xml.dist:

<?xml version="1.0"?>
<ruleset name="Theme">
    <arg name="tab-width" value="4"/>

    <rule ref="WordPress-Core">
        <exclude name="Generic.WhiteSpace.DisallowSpaceIndent"/>
    </rule>
    <rule ref="WordPress-Extra">
        <exclude name="Generic.WhiteSpace.DisallowSpaceIndent"/>
        <exclude name="WordPress.PHP.YodaConditions"/>
    </rule>

    <!-- (Optional) enforce no tabs for indent -->
    <rule ref="Generic.WhiteSpace.DisallowTabIndent"/>

    <file>functions.php</file>
    <file>inc/</file>
    <file>blocks/</file>
    <file>assets/functions/</file>
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>node_modules/*</exclude-pattern>
    <exclude-pattern>assets/dist/*</exclude-pattern>
    <exclude-pattern>assets/images/*</exclude-pattern>
    <exclude-pattern>assets/fonts/*</exclude-pattern>
    <exclude-pattern>assets/functionsLib/*</exclude-pattern>
    <exclude-pattern>*.js</exclude-pattern>
</ruleset>

Coding Standards Used

WordPress-Core

Includes the basic WordPress coding standards for:

Indentation and spacing
Naming conventions
Code structure
Security practices

WordPress-Extra

Extends WordPress-Core with additional rules for:

Documentation standards
Best practices
Code organization

Custom Exclusions

This template excludes certain rules:

Generic.WhiteSpace.DisallowSpaceIndent: Allows space indentation (normally WordPress uses tabs)
WordPress.PHP.YodaConditions: Disables Yoda conditions requirement
Forces tab indentation to be disallowed (uses spaces instead)

NPM Scripts

The package.json includes convenient scripts for PHPCS:

{
  "scripts": {
    "lint:php": "vendor/bin/phpcs --standard=.phpcs.xml.dist --colors .",
    "fix:php": "vendor/bin/phpcbf --standard=.phpcs.xml.dist --colors ."
  }
}

Available Commands

Check Code (Lint)

npm run lint:php

Scans PHP files for coding standard violations
Uses colors for better readability
Reports all issues without fixing them

Auto-Fix Code

npm run fix:php

Automatically fixes fixable coding standard violations
Uses the same configuration as the lint command
Reports which files were modified

Direct Composer Commands

You can also run PHPCS directly:

# Check for violations
vendor/bin/phpcs --standard=.phpcs.xml.dist --colors .

# Auto-fix violations
vendor/bin/phpcbf --standard=.phpcs.xml.dist --colors .

# Check specific file
vendor/bin/phpcs functions.php

# Show available coding standards
vendor/bin/phpcs -i

# Get help
vendor/bin/phpcs --help

File Coverage

PHPCS checks the following files and directories:

functions.php - Main theme functions file
inc/ - Include directory (if it exists)
blocks/ - Custom block PHP files
assets/functions/ - Theme function files

Excluded Patterns

vendor/* - Composer dependencies
node_modules/* - NPM dependencies
assets/dist/* - Build output files
assets/images/* - Image assets
assets/fonts/* - Font files
assets/functionsLib/* - Function library (excluded from standards)
*.js - JavaScript files (handled by other linters)

Integration with Development Workflow

Pre-commit Hooks

Consider adding PHPCS to your pre-commit hooks:

# Run PHPCS before each commit
npm run lint:php

IDE Integration

Most modern IDEs support PHPCS integration:

VS Code: PHP Sniffer extension
PhpStorm: Built-in PHPCS support
Sublime Text: PHP CodeSniffer plugin

Continuous Integration

Add PHPCS to your CI/CD pipeline:

# Example GitHub Actions
- name: Run PHPCS
  run: |
    composer install --no-dev --optimize-autoloader
    npm run lint:php

Common PHPCS Violations & Fixes

Array Syntax

// ❌ Wrong (old array syntax)
$array = array('key' => 'value');

// ✅ Correct (short array syntax)
$array = ['key' => 'value'];

Function Naming

// ❌ Wrong (camelCase)
function myCustomFunction() {}

// ✅ Correct (snake_case)
function my_custom_function() {}

WordPress Hooks

// ❌ Wrong (missing prefixes)
add_action('init', 'my_function');

// ✅ Correct (proper prefixing)
add_action('init', 'themename_my_function');

Troubleshooting

Common Issues

"WordPress" standard not found
- Run composer install to install WPCS
- Check if vendor/wp-coding-standards/wpcs exists
Config file not found
- Ensure .phpcs.xml.dist exists in theme root
- Use --standard=.phpcs.xml.dist explicitly
Memory issues with large projects
- Use --parallel=1 to disable parallel processing
- Exclude large directories with <exclude-pattern>

Debugging

# Show which files are being checked
vendor/bin/phpcs -v

# Show detailed ruleset information  
vendor/bin/phpcs -vv

# Show installed standards
vendor/bin/phpcs -i

Best Practices

Run PHPCS regularly during development
Fix violations immediately - don't let them accumulate
Use auto-fix first (npm run fix:php) then manually fix remaining issues
Customize rules in .phpcs.xml.dist to match project requirements
Document exceptions when excluding specific rules
Integrate with CI/CD to prevent violations from reaching production

Benefits

Consistent Code Style: All developers follow the same standards
Better Readability: Code is easier to read and understand
Fewer Bugs: Catches potential issues early
WordPress Compliance: Ensures code follows WordPress best practices
Team Collaboration: Reduces code review friction
Maintainability: Makes code easier to maintain long-term

This documentation is part of the BBC WordPress Starter Kit theme template.