Coding Standards

PHP and JavaScript coding standards, linting tools, and code review requirements for WooCommerce development

WooCommerce follows strict coding standards to ensure code quality, consistency, and maintainability across the entire codebase. This guide covers both PHP and JavaScript standards.

PHP Coding Standards

WooCommerce follows the WordPress Coding Standards for PHP code, with additional WooCommerce-specific requirements.

PHP Standards Overview

WordPress Standards

Base standards from WordPress core

WooCommerce Core

Additional WooCommerce-specific rules

PSR-4 Autoloading

Modern code in src/ directory

PHP Compatibility

Support for PHP 7.4+

Modern vs Legacy Code Architecture

WooCommerce has two distinct code styles based on directory structure:

Modern Code (src/)

plugins/woocommerce/
├── src/                    # Modern PHP code
│   ├── Internal/           # Internal classes (default)
│   └── [Public classes]    # Public API classes
│
# Standards:
# - PSR-4 autoloading
# - Dependency injection
# - Strict class naming (PascalCase)
# - Final classes by default
# - @internal tag for internal classes

PHP Linting Commands

Run these commands from the WooCommerce plugin directory:

# Lint all PHP files
pnpm --filter=@woocommerce/plugin-woocommerce lint:php

# Lint only changed files
pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes

# Lint changed files on current branch
pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes:branch

# Lint only staged files (pre-commit)
pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes:staged

# Auto-fix linting issues
pnpm --filter=@woocommerce/plugin-woocommerce lint:php:fix

The pre-commit hook will automatically run linting on staged PHP files before allowing a commit.

PHPStan Static Analysis

Before committing PHP changes, run PHPStan to catch type errors:

# Run PHPStan on modified files (from plugins/woocommerce directory)
composer exec -- phpstan analyse path/to/modified/File.php --memory-limit=2G

# Run PHPStan on all files
pnpm --filter=@woocommerce/plugin-woocommerce phpstan

# Update baseline if you've fixed baselined errors
pnpm --filter=@woocommerce/plugin-woocommerce phpstan:baseline

PHPStan failures often indicate the need to update the baseline file (phpstan-baseline.neon). If your fix resolves a previously baselined error, remove the corresponding entry from the baseline.

PHP Configuration (phpcs.xml)

The root phpcs.xml file defines the PHP_CodeSniffer rules:

phpcs.xml

<?xml version="1.0"?>
<ruleset name="WordPress Coding Standards">
  <!-- Base ruleset -->
  <rule ref="WooCommerce-Core" />
  
  <!-- Minimum supported versions -->
  <config name="minimum_supported_wp_version" value="5.2" />
  <config name="testVersion" value="7.4-" />
  
  <!-- Dependency injection for modern code -->
  <rule ref="WooCommerce.Functions.InternalInjectionMethod">
    <include-pattern>src/</include-pattern>
    <properties>
      <property name="injectionMethod" value="init"/>
    </properties>
  </rule>
  
  <!-- Strict class naming for modern code -->
  <rule ref="Squiz.Classes.ClassFileName">
    <include-pattern>src/</include-pattern>
  </rule>
</ruleset>

PHP Code Requirements

1. Namespace Requirements

   All modern code must use the Automattic\WooCommerce namespace:

   namespace Automattic\WooCommerce\Internal\Admin;
   
2. Dependency Injection

   Classes in src/ must use dependency injection via init() method:

   final class OrderController {
       private OrderRepository $repository;
       
       final public function init( OrderRepository $repository ) {
           $this->repository = $repository;
       }
   }
   
3. Documentation

   All classes and methods must have proper DocBlocks:

   /**
    * Handles order processing.
    *
    * @since 9.0.0
    * @internal
    */
   final class OrderProcessor {
       /**
        * Process an order.
        *
        * @param int $order_id Order ID.
        * @return bool True on success.
        */
       public function process( int $order_id ): bool {
           // Implementation
       }
   }
   
4. Type Hints

   Use PHP type hints for all parameters and return values (PHP 7.4+):

   public function get_order( int $id ): ?Order {
       return $this->repository->find( $id );
   }
   

JavaScript Coding Standards

JavaScript code follows the WordPress JavaScript coding standards via ESLint.

JavaScript Linting

# Lint JavaScript files
pnpm --filter=@woocommerce/plugin-woocommerce lint:lang:js

# Lint changed JavaScript on current branch
pnpm --filter=@woocommerce/plugin-woocommerce lint:changes:branch:js

# Lint with auto-fix
npx eslint --fix path/to/file.js

ESLint Configuration

The root .eslintrc.js extends WooCommerce ESLint plugin:

.eslintrc.js

module.exports = {
  root: true,
  extends: [ 'plugin:@woocommerce/eslint-plugin/recommended' ],
};

JavaScript Code Requirements

React Components

import { useState } from 'react';

/**
 * Order status display component.
 *
 * @param {Object} props Component props.
 * @param {number} props.orderId Order ID to display.
 * @return {JSX.Element} Component markup.
 */
export const OrderStatus = ( { orderId } ) => {
  const [ status, setStatus ] = useState( 'pending' );
  
  return (
    <div className="order-status">
      Status: { status }
    </div>
  );
};

TypeScript

interface Order {
  id: number;
  status: string;
  total: number;
}

/**
 * Fetches order by ID.
 */
export const fetchOrder = async ( 
  orderId: number 
): Promise<Order> => {
  const response = await fetch( `/api/orders/${ orderId }` );
  return response.json();
};

Testing

import { render, screen } from '@testing-library/react';
import { OrderStatus } from '../OrderStatus';

describe( 'OrderStatus', () => {
  it( 'renders order status', () => {
    render( <OrderStatus orderId={ 123 } /> );
    expect( screen.getByText( /Status:/ ) ).toBeInTheDocument();
  } );
} );

Code Review Requirements

Before submitting a pull request, ensure your code meets these requirements:

Pre-Commit Checklist

• All PHP code passes lint:php:changes without errors
• All JavaScript code passes lint:lang:js without errors
• PHPStan analysis passes on modified PHP files
• Code follows WordPress and WooCommerce coding standards
• All functions and classes have proper documentation
• Type hints are used for all parameters and return values (PHP)
• No hardcoded text strings (use i18n functions)
• Security best practices are followed (nonce verification, sanitization, escaping)
• Code supports minimum PHP (7.4+) and WordPress (5.2+) versions

Pre-Commit Hooks

The repository includes Husky pre-commit hooks that automatically run:

package.json (lint-staged)

{
  "lint-staged": {
    "*.php": [
      "php -d display_errors=1 -l",
      "composer run-script lint-staged"
    ],
    "!(*min).js": [
      "eslint --fix"
    ]
  }
}

The hooks will automatically fix many issues and prevent commits that don’t meet standards.

Editor Configuration

EditorConfig

Use EditorConfig to automatically configure your editor:

.editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.php]
indent_style = tab
indent_size = 4

[*.{js,json}]
indent_style = space
indent_size = 2

Always use LF (Unix) line endings, never CRLF (Windows). This is critical for Git consistency.

Common Standards Issues

Text Domain

All translatable strings must use the woocommerce text domain:

// ✅ Correct
__( 'Order status', 'woocommerce' );

// ❌ Incorrect - wrong domain
__( 'Order status', 'my-plugin' );

// ❌ Incorrect - missing domain
__( 'Order status' );

File Naming

Modern Code (src/)

# Class: Automattic\WooCommerce\Internal\Admin\OrderController
# File:  src/Internal/Admin/OrderController.php

✅ PascalCase class names
✅ Matches namespace structure

Legacy Code (includes/)

# Class: WC_Order_Controller
# File:  includes/admin/class-wc-order-controller.php

✅ Lowercase with hyphens
✅ Prefixed with 'class-'

Escaping and Sanitization

// ✅ Correct - escaped output
echo '<div>' . esc_html( $order->get_status() ) . '</div>';

// ❌ Incorrect - unescaped output
echo '<div>' . $order->get_status() . '</div>';

// ✅ Correct - sanitized input
$order_id = isset( $_POST['order_id'] ) 
    ? absint( $_POST['order_id'] ) 
    : 0;

// ❌ Incorrect - unsanitized input
$order_id = $_POST['order_id'];

Next Steps

Testing

Learn about testing requirements and commands

Git Workflow

Follow our Git workflow for contributions