Development

Development

This page covers the toolchain, the local-versus-lab split, coding standards and what is expected before a commit. It summarizes docs/en/development.md, CONTRIBUTING.md and docs/en/standards/coding-standards.md.

Prerequisites

Tool	Version	Notes
PHP	8.2+	Required by composer.json; PHP 7.2 syntax is still required in bootstrap files
Composer	2.4+	Needed for composer audit; a project-local PHAR may be used
Node.js	24	Pinned by .nvmrc; use nvm use
npm	10+	Ships with Node.js
Docker	Current stable	Only for container-based runs through the shared lab
WP-CLI	Current	Used by the integration wrapper outside CI
Git	2.34+	Conventional Commits; signed commits recommended

First-time setup

composer install     # locked PHP dependencies
npm ci               # locked Node dependencies
composer check       # static and unit gates before touching code
php -v && node -v

npm ci runs bin/prepare-wp-env.cjs through the postinstall hook, which prepares the pinned @wordpress/env copy. Development dependency overrides in package.json select patched compatible-major versions of ajv, qs, ws and related tooling; they are build tooling, not production plugin dependencies, and must be re-verified with a wp-env start plus npm audit whenever they change (docs/en/development.md).

Local versus shared lab

The split is mandatory, not advisory:

Work	Runs on	Why
PHPCS, PHPStan, PHPCompatibilityWP	Local	Pure static analysis, no services
Unit tests (composer test:unit)	Local	Brain Monkey and Mockery, no database
Packaging and ZIP regressions	Local	Structural fixtures only
Integration, multisite, network	Shared lab toolbox	Needs real WordPress, MySQL and InnoDB
HTTP security matrix	Shared lab toolbox	Needs real HTTPS and a second plain-HTTP service
Browser E2E and accessibility	Shared lab browser	Needs Playwright and disposable sites

Do not start Docker, a database or a browser on this workstation for these suites. The lab is reached through the shared lc-udev-remote-test-lab skill and its rtl.py entry point; the npm scripts env:start, env:stop, remote:plan, remote:up and test:e2e are thin wrappers around it (package.json). Read the rendered plan before deploying it, keep volumes on stop, and never purge data you do not own.

CI keeps a disposable wp-env path for hosted runners. That path is for GitHub Actions, not for local development (bin/test-integration.sh branches on CI=true).

Coding standards

• Language. Source code, comments, docblocks, UI source strings, commit messages and canonical documentation are English. Translate only through the xnetvn-agent-hub-wp text domain. Ability descriptions stay fixed English because MCP clients consume them (CONTRIBUTING.md, AGENTS.md).
• Formatting. WordPress Coding Standards: WordPress-Extra, WordPress-Core, WordPress-Docs, configured in phpcs.xml.dist. Tabs in PHP; two spaces in YAML, JSON, Markdown, CSS and JavaScript.
• Static analysis. PHPStan level 8 with no baseline (phpstan.neon.dist, composer analyse).
• Strict types. declare(strict_types=1); in every PHP file under src/ and tests/.
• Compatibility. Runtime code targets PHP 8.2. The entry file, uninstall.php and src/Bootstrap/*.php must parse on PHP 7.2, because they run before the requirements gate (composer lint:bootstrap).
• Docblocks. WordPress PHP Documentation Standards: summary line, full @param/@return/@throws, units, ranges and security notes (docs/en/standards/coding-standards.md).
• Forbidden. Dead or commented-out code, magic numbers, hardcoded secrets, copy-pasted third-party implementations.

Pre-commit expectations

Run the full local gate before requesting review:

composer check          # lint, bootstrap syntax, PHPStan, version, invariants, unit, docs, skills
composer test:packaging # release exclusion regressions
composer build          # build and structurally verify the release ZIP

composer check is defined in composer.json as the sequence lint, lint:bootstrap, analyse, check:version, check:repo, test:unit, check:docs, check:skills. The documentation part compares documented setting defaults with WpSiteSettings::DEFAULTS and checks English/Vietnamese parity plus every relative documentation link (bin/check-settings-docs.py, bin/check-docs-parity.py). check:repo verifies the repository invariants and their self-test (bin/check-repo-invariants.sh); check:skills validates the public skill pack (bin/check-skills.py).

Add integration coverage when a change touches REST, the MCP route, ability execution, audit, persistence or uninstall, and add negative tests for every security check you touch (CONTRIBUTING.md). Behavior changes follow red-green-refactor: write the failing test first.

Documentation stays with the code

A behavior change updates its documents in the same pull request: hooks and routes in docs/en/architecture/overview.md, schemas in the ability catalog, configuration in docs/en/INSTALL.md and docs/en/ENVIRONMENT.md, translation strings via bash bin/make-pot.sh, and every user-visible change in CHANGELOG.md (CONTRIBUTING.md). The Vietnamese tree under docs/vi/ mirrors English, and the parity check fails if the two drift.

Environment notes

• XNETVN_AGENT_HUB_WP_ALLOW_INSECURE permits plain HTTP only in an explicit local or development environment. Never enable it in production (docs/en/ENVIRONMENT.md).
• Do not run wp-env clean on an environment that holds valuable data; smoke uninstall tests must use disposable sites or packaged copies, because uninstall deletes plugin files and data (docs/en/development.md).
• PHP 8.5 integration and WordPress trunk remain experimental until compatibility evidence is recorded. CI defines PHP 8.2–8.5 unit checks.
• npm run test:tooling runs the dependency contracts used by CI.

Branch, review and commit rules are on Contributing; the command matrix with proof boundaries is on Testing.