rlorenzo / mago-wordpress

v1.2.0 2026-10-02 00:53 UTC

Requires

• php: ^8.1
• ext-dom: *
• ext-libxml: *
• ext-tokenizer: *
• carthage-software/mago: ^1.47.1

Requires (Dev)

• phpunit/phpunit: ^10.5 || ^11.5 || ^12.0

MIT

• Rex Lorenzo

• linter
• wordpress
• static-analysis
• coding-standards
• wpcs
• mago

Published on Packagist.org on 2026-10-02 00:54 UTC

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.

2–12× faster than phpcs

8.1× faster overall on the top 10 WordPress.org plugins plus WordPress core. Method and numbers: Benchmarks.

Install

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

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

Run mago lint. You get this package's 52 default rules, Mago's own WordPress security rules and a WordPress formatter preset.

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

mago format can't add the spaces WordPress puts inside parentheses, so a lint fix adds them afterwards. Always run the three steps together, because mago format removes the spaces again:

mago lint --fix --only array-style
mago format
mago lint --fix --only wordpress/parentheses-spacing

See Formatting.

Docs

• Rules: the 53 rules, their levels and their autofixes.
• 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.
• 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.