README

WordPress Coding Standards for Mago. This extension ports the WPCS lint sniffs to Mago's linter, so a plugin or theme is checked in seconds, not minutes.

About 2× faster than phpcs on large plugins

1.8× faster overall on the top 10 WordPress.org plugins plus WordPress core: about 2–2.7× on the large plugins, about even on the small ones. Method and numbers: Benchmarks.

Install

composer require --dev carthage-software/mago rlorenzo/mago-wordpress

# mago.toml
extends = "vendor/rlorenzo/mago-wordpress/wordpress-extra.mago.toml"

Pick the preset that matches the phpcs standard you used. If you're not sure, use wordpress-extra.mago.toml: WordPress-Extra is what most plugins and themes run.

phpcs `--standard`	Preset
`WordPress-Core`	`wordpress-core.mago.toml`
`WordPress-Extra`	`wordpress-extra.mago.toml`
`WordPress` (Core + Docs + Extra + the database and input sniffs)	`wordpress.mago.toml`

Run mago lint. Each preset reports what its standard reports: the rules for sniffs outside it are off, and so are Mago's own rules that no WPCS sniff runs (strict-types, no-isset, cyclomatic-complexity and the like), so a project that was clean under phpcs starts clean. All three include a WordPress formatter preset.

Each rule reports at WPCS's level, and mago lint fails only on errors. phpcs also failed on warnings, so pass --minimum-fail-level warning to keep that. phpcs -n corresponds to --minimum-report-level error. See Migrating.

Switching a project with phpcs in CI and a pre-commit hook: Adopting walks through config, suppressions, baseline, CI, hooks and formatting.

The worker runs as PHP inside your project and loads its Composer autoloader, like PHPUnit or PHPStan, so only lint projects you trust.

Configure

Settings go in composer.json:

{
  "extra": {
    "mago-wordpress": {
      "text-domains": ["my-plugin"],
      "prefixes": ["myplugin"],
      "minimum-wp-version": "6.4"
    }
  }
}

Already using phpcs? Without this block, the same settings and exclusions are read from your phpcs.xml.
Existing phpcs:ignore and phpcs:disable comments still work.
Turn a rule off with exclude-patterns, under its WPCS code. [linter.rules] doesn't accept wordpress/* codes.

All settings: Configuration.

Migrate from phpcs

vendor/bin/mago-wordpress migrate          # print the mago.toml and composer.json settings
vendor/bin/mago-wordpress migrate --write  # save them

It also lists anything it couldn't carry over. See Migrating from phpcs.

Format

vendor/bin/mago-wordpress format          # format
vendor/bin/mago-wordpress format --check  # CI: fail with a diff if anything would change

The layout sniffs are lint rules too: mago lint reports them and mago lint --fix fixes them. mago format alone can't add the spaces WordPress puts inside call, declaration and control-structure parentheses, so don't use it (or an editor's Mago format-on-save) on WordPress code: mago-wordpress format runs it and then the fixes that restore WordPress's layout, and leaves a file as it was if formatting would raise the number of findings of any rule. See Formatting.

Docs

Rules: every rule with its level and autofix.
Configuration: every setting, the phpcs.xml fallback and suppression comments.
Formatting: the preset and what still differs from WPCS.
Migrating from phpcs: what migrate converts and what it can't.
Adopting: moving a phpcs project over, step by step, with CI and hooks.
WPCS coverage: Mago's own WordPress rules, WordPress-Docs, the generic sniffs, and what isn't ported.
Benchmarks: method and full results.

Development

composer install   # also points git at .githooks (pre-commit runs `just check`)
just check         # composer validate, format-check, PHPUnit, mago lint + analyze, corpus

Rule tests run a real Mago worker against tests/corpus/rules/<rule>/. Each expected report is marked with // @mago-expect lint:wordpress/<rule> on the line before it, and any report without a matching expectation fails. CI runs just check on PHP 8.1, 8.4 and 8.5.

Credits

Generic syntax helpers are adapted from amateescu/mago-drupal (MIT) and the rule data from WordPress Coding Standards (MIT); see NOTICE.md. The rules were first written in Rust for the Mago fork at rlorenzo/mago and ported here after Mago gained worker extensions.

rlorenzo / mago-wordpress

Package info

Security

Fund package maintenance!

Statistics