WP Coding Standards

To maintain high-quality, readable, and consistent code, this project adheres strictly to the WordPress Coding Standards (WPCS). All contributions must pass linting via PHP_CodeSniffer using the WordPress-Core, WordPress-Docs, and WordPress-Extra rulesets.

Prerequisites

Before submitting a Pull Request, ensure you have the following installed locally:

Composer: Used to manage PHP dependencies and the linting engine.
PHP 7.4+: The minimum supported version for our development environment.

Setup and Installation

The project includes a pre-configured phpcs.xml.dist file. To install the necessary tools, run:

composer install

This will install squizlabs/php_codesniffer and the WordPress-Coding-Standards ruleset into your vendor directory.

Linting Your Code

To check your code for violations against the WordPress standards, execute the following command from the root directory:

# Check all files in the repository
./vendor/bin/phpcs .

# Check a specific file or directory
./vendor/bin/phpcs path/to/your-file.php

Understanding the Output

The sniffer will provide a report highlighting:

Line Number: Location of the violation.
Type: Error (must fix) or Warning (should fix).
Message: A description of the standard being violated (e.g., "Missing docblock", "Space expected after comma").

Automatic Fixing

Many formatting issues (such as indentation, spacing, and brace placement) can be fixed automatically using the PHP Code Beautifier and Fixer (phpcbf):

# Automatically fix issues in the current directory
./vendor/bin/phpcbf .

Note: phpcbf cannot fix logical errors or security-related issues (like missing sanitization). These must be addressed manually.

Key Guidelines

While the linter handles the technicalities, please keep these core WordPress principles in mind:

| Standard | Description | Example | | :--- | :--- | :--- | | Naming Conventions | Use lowercase and underscores for functions, variables, and file names. | my_function_name(), $user_id | | Sanitization | Always sanitize user input before usage. | sanitize_text_field( $_POST['user_input'] ) | | Escaping | Always escape data before outputting to the browser. | echo esc_html( $variable ) | | Indentation | Use Tabs for indentation, not spaces. | \t | | Braces | Always use braces, even for single-line statements. | if ( $val ) { ... } |

Editor Integration

For a better development experience, we recommend integrating phpcs directly into your IDE:

VS Code: Install the phpcs extension and point it to ./vendor/bin/phpcs.
PhpStorm: Go to Settings > PHP > Quality Tools > PHP_CodeSniffer and select the project's local executable.

Failure to follow the coding standards will result in automated build failures and may delay the review process.