Download the PHP package apermo/apermo-coding-standards without Composer

Apermo WordPress Coding Standards

Shared PHPCS ruleset for WordPress projects. Combines WordPress Coding Standards, Slevomat type hints, YoastCS, and PHPCompatibility into a single reusable standard.

Requirements

• PHP 7.4+

Installation

The Composer Installer Plugin automatically registers the standard with PHPCS.

Usage

Reference the Apermo standard in your project's phpcs.xml:

Then run:

Project Configuration

The Apermo standard includes rules that require project-specific settings. Without these, you either get false positives or miss valid warnings. Copy phpcs.xml.dist.example as a starting point, or add the properties below to your existing phpcs.xml.

Text Domain (text_domain)

WordPress.WP.I18n validates that all translation calls use the correct text domain. Set this to your plugin or theme slug:

Global Prefixes (prefixes)

WordPress.NamingConventions.PrefixAllGlobals checks that global functions, hooks, constants, and namespace declarations use your project prefix. Two entries are needed because the namespace root is PascalCase while the function/hook prefix is snake_case:

The PascalCase entry allows namespace My_Plugin\Admin; but flags namespace Other\Admin;. The snake_case entry validates function names like my_plugin_init() and hook names like my_plugin_loaded.

For nested namespace roots (e.g. a vendor namespace), set the full root:

This allows namespace Acme\My_Plugin\Admin; but flags namespace Acme\Other;.

Minimum WordPress Version (minimum_wp_version)

Controls which WordPress functions are flagged as deprecated. Set this to the oldest WordPress version your project supports:

What's Included

Notable Opinions

• Short array syntax ([]) enforced, long array syntax (array()) forbidden
• Short ternary operators allowed
• Yoda conditions disallowed
• Short open echo tags (<?=) allowed
• Type hints enforced for parameters, return types, and properties
• Closures limited to 5 lines
• Use statements must be alphabetically sorted
• Unused imports are flagged
• No more than 1 consecutive empty line (file-level, class-level, between functions)
• require/require_once enforced over include/include_once
• elseif enforced over else if
• Unconditional if statements (if (true)) are errors
• stdClass usage discouraged — new \stdClass() and (object) casts warned
• Hook invocations (do_action, apply_filters) require PHPDoc blocks
• Assignment alignment must be consistent within groups (all aligned or all single-space)
• Nested closures and arrow functions are warned
• exit() enforced over die and bare exit
• Variable names must be at least 4 characters (configurable allowlist)
• Closures must be static when not using $this
• Trailing comma required in multi-line function calls
• Functions limited to 50 lines, classes to 500 lines
• Cognitive complexity flagged (warning > 15, error > 30)
• Unused local variables flagged
• Implicit array creation ($a[] = on undefined) flagged
• ?? required instead of isset() ternary
• Short type hints enforced in PHPDoc (int not integer)
• null must be last in union types (string|null not null|string)
• and/or operators disallowed (use &&/||)
• Alternative control syntax (endif, endwhile) disallowed
• register_rest_route() must include permission_callback
• FILTER_SANITIZE_STRING and related deprecated constants flagged
• add_option()/update_option() must include explicit autoload parameter
• Docblock summaries must be third-person singular per the WordPress documentation standard (Displays… not Display…, no Allows you to… / Lets you… anti-patterns)

REST Permission Callback (Apermo.WordPress.RequireRestPermissionCallback)

Flags register_rest_route() calls without a permission_callback in the args array. Omitting this callback leaves the endpoint open to unauthenticated access — the #1 REST API security hole.

Only array literal args are checked. Variable or function call args are assumed correct (cannot verify statically).

Customization via phpcs.xml:

No Filter Sanitize String (Apermo.PHP.NoFilterSanitizeString)

Flags deprecated PHP filter constants that give a false sense of security:

Customization via phpcs.xml:

Require Option Autoload (Apermo.WordPress.RequireOptionAutoload)

Warns when add_option() or update_option() is called without an explicit autoload parameter. The default behavior loads the option on every page request — a common performance footgun for options that are rarely needed.

Customization via phpcs.xml:

Exit Usage (Apermo.PHP.ExitUsage)

Enforces exit() as the canonical form. Flags die, die(), and bare exit (without parentheses). Auto-fixable with phpcbf.

Customization via phpcs.xml:

Minimum Variable Name Length (Apermo.NamingConventions.MinimumVariableNameLength)

Warns on variable names shorter than 4 characters (excluding $). Common short names are allowed by default: i, id, key, url, row, tag, map, max, min, sql, raw.

Customization via phpcs.xml:

Text Domain Validation

WordPress.WP.I18n text domain checking is active via the WordPress ruleset. See Project Configuration for setup instructions.

Forbidden Nested Closures (Apermo.Functions.ForbiddenNestedClosure)

Closures and arrow functions nested inside other closures or arrow functions are warned. Extract the inner callback to a named function instead.

Customization via phpcs.xml:

Commented-Out Code (Apermo.PHP.ExplainCommentedOutCode)

Commented-out PHP code in // comments must be preceded by a /** */ doc-block explanation starting with a recognized keyword:

Examples:

An optional date in YYYY-MM-DD format can be added in parentheses after the keyword.

Supersedes Squiz.PHP.CommentedOutCode — that rule is disabled automatically.

Customization via phpcs.xml:

Multiple Empty Lines (Apermo.WhiteSpace.MultipleEmptyLines)

No more than one consecutive empty line is allowed outside functions and closures. Inside functions, Squiz.WhiteSpace.SuperfluousWhitespace already enforces this.

Auto-fixable with phpcbf.

Customization via phpcs.xml:

Require Not Include (Apermo.PHP.RequireNotInclude)

include and include_once are forbidden because they silently continue on failure. Use require/require_once instead.

Not auto-fixable (changing include to require may alter behavior).

Use // phpcs:ignore Apermo.PHP.RequireNotInclude to suppress when include is genuinely intended.

Separate error codes (IncludeFound, IncludeOnceFound) allow independent configuration:

Array Complexity (Apermo.DataStructures.ArrayComplexity)

Flags deeply nested or wide associative arrays that would benefit from typed objects (DTOs, value objects). Arrays with many string keys or deep nesting often indicate data structures that should be classes.

Three independent checks. The first two apply to array literals (advisory, since literals often mirror external WordPress API shapes the caller does not own). The third applies to custom function, method, and closure parameters whose default value or PHPStan/Psalm @param array{...} shape is complex — those are errors, because the signature author owns the shape and can refactor to a DTO.

Default thresholds for literals are tuned so idiomatic WordPress usage (a WP_Query call with meta_query, a 7-key arg set to register_post_type, etc.) stays silent. Genuinely monolithic shapes still surface.

Only outermost literal arrays are checked — nested sub-arrays are not reported separately. Numeric arrays (without =>) are ignored entirely. The canonical fix for a literal TooDeep warning is to extract the complex sub-array into its own variable.

Customization via phpcs.xml:

Global Post Access (Apermo.WordPress.GlobalPostAccess)

Flags global $post; inside functions, methods, closures, and arrow functions. Top-level (template) usage is allowed because the WordPress loop sets $post there. Functions should receive WP_Post or a post ID as a parameter.

Implicit Post Function (Apermo.WordPress.ImplicitPostFunction)

Flags WordPress template functions called without an explicit post argument inside function scopes. These functions implicitly read the global $post, creating hidden dependencies.

Severity depends on what was passed, not which function:

Customization via phpcs.xml:

Forbidden stdClass (Apermo.PHP.ForbiddenObjectCast + SlevomatCodingStandard.PHP.ForbiddenClasses)

Discourages stdClass usage in favor of typed classes. Two rules work together:

• Apermo.PHP.ForbiddenObjectCast warns on (object) casts
• SlevomatCodingStandard.PHP.ForbiddenClasses warns on new \stdClass()

Both emit warnings (not errors) to allow gradual migration.

Customization via phpcs.xml:

Hook Documentation (Apermo.Hooks.RequireHookDocBlock)

WordPress hook invocations (do_action, apply_filters, and their _ref_array and _deprecated variants) must be preceded by a PHPDoc block.

The sniff checks:

All violations are errors.

Customization via phpcs.xml:

Docblock Summary Style (Apermo.Commenting.DocSummaryStyle)

Enforces third-person singular docblock summaries per the WordPress PHP Documentation Standards. The rule of thumb: prepending "It" to the summary must read grammatically — Displays the post title. ("It displays…") passes; Display the post title. ("It display…") does not.

Applies to function, method, class, interface, trait, and enum docblocks. Property, constant, and bare-variable docblocks are skipped — their summaries are idiomatically noun-form.

Three layered checks, evaluated in order. First match wins.

Whitelist (pass-through): Callback, Wrapper, Helper, Utility, Alias, Shortcut. Common noun-lead openers that WordPress style tolerates.

All violations are warnings. No autofixer — rewriting verb forms reliably requires handling irregulars (Do→Does, Have→Has, Go→Goes) that a naive +s rule gets wrong.

Customization via phpcs.xml:

Consistent Assignment Alignment (Apermo.Formatting.ConsistentAssignmentAlignment)

Consecutive assignment statements must use a consistent style: either all = operators are aligned to the same column, or all use a single space before =. Mixing styles within a group is warned. Auto-fixable with phpcbf — deviators are adjusted to match the majority style.

Groups where all operators are aligned but padded beyond the longest variable + 1 space are flagged as OverAligned errors (not auto-fixable).

A group of assignments breaks on: blank lines, non-assignment statements, or EOF.

Supersedes Generic.Formatting.MultipleStatementAlignment — that rule is disabled automatically.

Customization via phpcs.xml:

Consistent Double Arrow Alignment (Apermo.Arrays.ConsistentDoubleArrowAlignment)

Multi-line associative arrays must use a consistent => style: either all arrows are aligned to the same column, or all use a single space before =>. Mixing styles within an array is warned. Auto-fixable with phpcbf — deviators are adjusted to match the majority style.

Arrays where all arrows are aligned but padded beyond the longest key + 1 space are flagged as OverAligned errors (not auto-fixable).

Only outermost arrays are checked — nested sub-arrays are analyzed independently. Single-line arrays are skipped.

Supersedes WordPress.Arrays.MultipleStatementAlignment — that rule is disabled automatically.

Customization via phpcs.xml:

Elseif Over Else If (PSR2.ControlStructures.ElseIfDeclaration)

else if must be written as elseif. Upgraded from the PSR2 default warning to an error.

Auto-fixable with phpcbf.

Custom Sniffs

Place custom sniffs in Apermo/Sniffs/<Category>/<SniffName>Sniff.php. PHPCS discovers them automatically.

Example: Apermo/Sniffs/Naming/FunctionPrefixSniff.php is referenced as Apermo.Naming.FunctionPrefix.

Contributing

Development

Release Process

1. Create a release/X.Y.Z branch from main
2. Update CHANGELOG.md with the version heading and release date
3. Open a PR — CI runs tests, PHPStan, and validates the changelog
4. Merge the PR — GitHub Actions creates a draft release with the tag
5. Review and publish the draft release on GitHub

AI Disclaimer

This project is developed with major assistance from Claude Code (Anthropic). Claude handles the bulk of the implementation — writing sniffs, tests, fixtures, CI workflows, and documentation — while the maintainer reviews, steers, and makes final decisions. Projects with stricter rules regarding the use of AI-generated code should refrain from forking or reusing code from this repository.

License

MIT