claude-websimple-devops/references/wp-code-style.md

WP Code Style

Use this skill for PHP source formatting and coding-standard checks in Websimple WordPress projects.

Shared tooling model

Websimple WordPress projects should rely on shared/global Websimple PHPCS tooling, not per-project Composer installs.

Project repos should keep only project-specific lint scope in phpcs.xml. The PHPCS binary, PHPCBF binary, and WebsimpleWP ruleset should come from global Composer tooling.

Expected global setup, only when explicitly asked to install or repair tooling:

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require squizlabs/php_codesniffer lewebsimple/wp-phpcs-ruleset

If global Composer binaries are not on PATH, locate them with:

composer global config bin-dir --absolute --quiet

When cleaning an existing project, remove per-project Composer ownership of PHP_CodeSniffer and Websimple coding-standard tooling:

• remove squizlabs/php_codesniffer from require-dev when present;
• remove lewebsimple/wp-phpcs-ruleset from require-dev when present;
• remove lint / lintfix Composer scripts when they only wrap project-local PHPCS/PHPCBF, such as vendor/bin/phpcs or vendor/bin/phpcbf.

Preserve unrelated Composer dependencies and scripts. If a script does more than run PHPCS/PHPCBF, ask before removing or rewriting it.

Required phpcs.xml

Make sure phpcs.xml exists at the project root and only includes wp-content/mu-plugins/ plus the active/current theme directory:

<?xml version="1.0"?>
<ruleset name="wp-code-style">
  <rule ref="WebsimpleWP"/>
  <file>wp-content/mu-plugins/</file>
  <file>wp-content/themes/${theme}/</file>
</ruleset>

Resolve ${theme} from the active child/current theme or from the user’s target. Do not lint all themes, WordPress core, vendor, uploads, cache, generated assets, or unrelated directories.

Workflow

1. Inspect composer.json, composer.lock, and any existing phpcs.xml / phpcs.xml.dist.
2. Resolve the target theme with WP-CLI or source inspection.
3. Remove project-local PHPCS/ruleset Composer dependencies and simple lint / lintfix scripts when present.
4. Ensure phpcs.xml is present and scoped correctly.
5. Run lint with global phpcs from the shell, not vendor/bin/phpcs.
6. Use global phpcbf only when the user requested formatting or the fix is clearly safe.
7. Re-run lint after fixes and inspect the diff before claiming success.

Safety

• Do not run PHPCBF across broad paths unless the phpcs.xml scope is correct.
• Do not modify vendor, WordPress core, uploads, caches, or compiled assets.
• If PHPCBF changes files, summarize changed files and remaining PHPCS issues.
• Do not remove Composer scripts that contain extra behavior beyond straightforward PHPCS/PHPCBF wrappers without asking first.