Documentation · Developer Documentation

Coding Standards

This page describes the conventions a contribution to the plugin should follow, at a level that is safe to publish. Internal class names, internal constants, capability identifiers and option-key conventions are implementation details and are not published here.

When to use this document

Use this document when you:

  • Are about to add PHP, JavaScript, CSS, templates or translatable strings to a contribution.
  • Are reviewing a pull request and need a reference for what "consistent with the codebase" means.
  • Are extending the plugin from a separate plugin or a theme and want your own code to feel native.

PHP

  • Language level. Target the PHP version declared in the plugin header as the minimum. Avoid features that are not available there.
  • Type declarations. Use scalar and return type declarations on new methods, in line with surrounding code.
  • WordPress style. Follow the WordPress PHP coding standards (tabs for indentation, spaces inside parentheses, Yoda conditions where the codebase already uses them, snake_case for functions and methods, TitleCaseWith_Underscores for class names).
  • Single class per file. Each PHP file contains one class. File names match class names in lowercased-and-hyphenated form, consistent with the conventions already present in the codebase.
  • No new globals. Prefer class constants and dependency injection over scattered globals.

WordPress integration

  • Capability checks first. Every privileged action must verify the appropriate capability before doing any work.
  • Nonce checks for forms and admin AJAX. Use the standard WordPress nonce APIs (check_admin_referer, check_ajax_referer, wp_verify_nonce) for any state-changing endpoint.
  • Sanitisation and escaping. Sanitise on input and escape on output using the appropriate WordPress APIs for the type and the output context. See Sanitization And Escaping.
  • i18n. Wrap user-facing strings with the plugin's text domain. See Internationalization For Developers.
  • Logging. Use the plugin's shared logger rather than calling PHP's error_log directly from new feature code.

JavaScript and CSS

  • The plugin does not use a JavaScript build pipeline; assets ship as plain files.
  • Keep front-end JavaScript dependency-free and progressive; the plugin must continue to work in browsers that block third-party scripts.
  • Prefix new CSS classes consistently with the existing front-end and admin conventions to avoid collisions with themes.

Tests

  • New behavioural changes should be covered by tests where they can reasonably be exercised by unit tests.
  • Name new test classes after the class or behaviour under test with a Test suffix, in line with existing tests.
  • See Testing Guide for the high-level test workflow.

Documentation

  • Update the relevant pages under docs/en/ whenever a contribution changes publicly observable behaviour.
  • Keep documentation public-safe; do not add internal class names, option keys, REST/AJAX route names or capability/nonce identifiers to the public documentation set.

Public documentation notice. This page provides a high-level integration overview only. Internal implementation details, private APIs, storage internals and security-sensitive release infrastructure are maintained separately and are not part of the public documentation.