63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# 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.
|