# 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:

```bash
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:

```bash
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
<?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.