ddtcorex/maestro-skills/govard-wordpress

Govard WordPress Commands

WordPress-specific shortcuts and commands for Govard environments.

Related Skills

REQUIRED BACKGROUND: Load govard-toolbox first. This skill only covers WordPress-specific behavior layered on top of Govard's base environment commands (govard up, govard sh, govard db, remote sync, Xdebug setup). For generic PHP (strict_types, PSR-12, PHPStan, security) see php-dev-core.

Docker requirement: stack commands here need Docker. Check what a command needs with govard capabilities. Unlike some frameworks, WordPress has no container-free govard audit run --checks integrity (it fails with "does not support integrity audit").

WP-CLI

wp runs inside the PHP container. govard up installs it when missing.

govard tool wp --info
govard tool wp core version
govard tool wp plugin list
 
# Alternative: open a shell, then run wp directly
govard sh
wp --info

Most wp commands that touch the database (plugin list, theme list, cache flush, rewrite flush) fail with "The site you have requested is not installed" until the site is installed. A checkout brought up with govard up has wp-config.php wired to the Govard database but an empty database, so installing is your step, not a red flag:

govard tool wp core install --url=https://<project-domain> --title="Local" --admin_user=admin --admin_email=admin@example.com
govard tool wp core is-installed && govard db query "SHOW TABLES"

(govard bootstrap --fresh runs the install itself.) Read the project's runtime values instead of assuming them:

govard config get stack.php_version
govard config get stack.db_version
govard config get domain

govard bootstrap --framework-version <v> is pinned, not "latest": a bare 6 is normalised to 6.0 and that exact archive is downloaded from wordpress.org. Omit the flag to track latest. Bedrock layout (web/wp/wp-includes/version.php) is auto-detected (see govard-toolbox for provider details).

Audit

Lint is the supported check: govard audit run --checks lint --lint-provider govard --mode project --format json (see govard-toolbox ## Audit for the cross-framework matrix). On WordPress:

• --checks integrity and --checks profiler are not supported (exit 1, "framework wordpress does not support ... audit").
• With Xdebug enabled (the default in many .govard.yml files) audit refuses to run: pass --allow-xdebug or run govard config set stack.features.xdebug false first.
• Linting a full WordPress tree can take minutes and exits 1 when it reports findings; scope with --scope diff --base <ref> for day-to-day use.

Cache Management

# Object cache (needs an installed site; a no-op without an object-cache drop-in)
govard tool wp cache flush
 
# Transients
govard tool wp transient delete --all
 
# Caching plugins expose their own wp subcommands; they only work once the plugin is installed
govard tool wp rocket clean --confirm

There is no Govard-level frontend_sync for WordPress; use govard tool npm run watch if the theme has a build step.

Plugin & Theme Management

govard tool wp plugin list
govard tool wp theme list
 
govard tool wp plugin install query-monitor --activate
govard tool wp theme install twentytwentyfour --activate
 
govard tool wp plugin update --all
govard tool wp theme update --all

Must-use plugins live in wp-content/mu-plugins and are not managed by wp plugin.

Rewrite & Core

# After CPT/taxonomy changes. Warns "Rewrite rules are empty" until a permalink structure is set.
govard tool wp rewrite flush
govard tool wp rewrite list
 
govard tool wp core verify-checksums   # exits 1 if any core file was modified
 
# After a domain change (e.g. staging sync); try --dry-run first
govard tool wp search-replace 'https://staging.example.com' 'https://<project-domain>' --all-tables

wp-config.php is generated (DB credentials, fresh salts, proxy/HTTPS support) only when it is missing at bootstrap time. govard up does not rewrite an existing wp-config.php or regenerate its salts. For multisite, add extra_domains in .govard.yml for each site domain, then govard env up:

extra_domains:
  - shop.<project-domain>

govard domain add|remove|list manages the same list.

Database

govard db info                                  # connection details, never the password
govard db query "SHOW TABLES"
govard db query "SELECT option_value FROM wp_options WHERE option_name='siteurl'"
 
govard db dump --file backup.sql
govard db import --file backup.sql --drop       # --drop recreates the database first
govard db dump --no-noise --no-pii -e staging   # privacy-filtered dump from a remote
 
# Same thing through WP-CLI inside the container
govard tool wp db query "SHOW TABLES"
govard tool wp db export --add-drop-table

Privacy filters match by table name, so they need the prefix. --no-noise and --no-pii exclude WordPress tables (users, usermeta, comments, commentmeta for PII; a few cache/log tables for noise) with the table prefix prepended. Govard reads the literal $table_prefix from wp-config.php, locally and, for a remote, from the remote's own wp-config.php through the credentials probe. It never borrows the local prefix for a remote.

--no-pii fails closed: when no table can match (the remote's prefix cannot be read, or $table_prefix is built dynamically, for example from getenv()), the command is refused instead of writing a dump that still holds wp_users. --no-noise and --plan only warn. Still spot-check a dump before sharing it (grep -c 'INSERT INTO wp_users' must be 0). db dump -e <remote> --file <path> writes <path> on the remote; add --local to stream the dump into the project's var/ directory.

Environment

• Do not commit wp-config.php secrets.
• For staging/prod overrides use GOVARD_ENV=staging govard env up (loads .govard.staging.yml).
• Xdebug: govard debug on|off|status (off rewrites .govard.yml and re-runs env up).
• govard shell -c "..." / govard sh -c "..." run one command in the PHP container.

Deployment

WordPress ships a deploy recipe for the classic layout only: core files and wp-content/ in the repository root. A Bedrock layout (core in vendor/, docroot web/) and a content-only checkout are not supported.

govard deploy plan production --branch main   # resolved pipeline: no connection, no Docker
govard deploy check production --branch main  # preflight over ssh
govard deploy production --branch main --yes

The remote needs a branch (--branch, --revision, --tag, or a configured branch) for plan, and a deploy_path (or an existing deploy layout) for check/status; otherwise they exit 4. Add --json to plan for machine-readable output. See govard deploy --help for every flag.

Three steps are hybrids: wp when the target has wp-cli, a wp-load.php PHP bootstrap when it does not.

• Seed `shared/wp-config.php` before the first deploy. deploy:shared links a shared entry only when it already exists, so an unseeded shared/ leaves the release with the repository's wp-config.php, the one naming the development database. The first run fails at db:migrate ("Error establishing a database connection"), and the lock and release directory are kept. Seeding afterwards does not repair that release: --resume skips deploy:shared as already done (and --from does not re-run it), so link the shared file into the release by hand (ln -sfn <deploy_path>/shared/wp-config.php <release>/wp-config.php) before resuming, or start a fresh release. In one resumed run the unlinked release passed db:migrate and was activated before app:cache:flush failed with the same connection error, so an unseeded release can go live.
• deploy:check refuses a verify URL that redirects. A database copied from another environment keeps that environment's siteurl, so WordPress answers the verify URL with a 301 and the preflight stops. The sandbox seed rewrites siteurl/home to its own URL; for any other target point siteurl/home at the target URL (wp option update), or set deploy.verify.follow_redirects: true.
• Maintenance writes time() + 86400, not WordPress's own time(): a flag older than ten minutes expires, so a longer window would silently reopen the site mid-migration. The drop-in carries a marker, so a project's own maintenance page is kept. A deploy that fails after maintenance:enable leaves the flag and the lock behind; --resume (after deploy unlock --force if the lock is fresh) finishes the release and removes the flag.
• --db-backup uses wp db export/wp db import when the target has wp-cli, and otherwise a plain mariadb-dump/mysqldump that reads wp-config.php and hands the credentials to the client through a private option file (never on a command line). A target with none of the three is refused up front as a configuration error (exit 4). Without the flag the db:backup row is reported as skipped, with the reason. With it the dump lands in shared/backups/deploy/<release>/dump.sql.
• deploy rollback --with-db restores the dump recorded by the release after the rollback target, and refuses (exit 1) when that release has none, for example the newest one.
• deploy unlock refuses a fresh lock without --force. deploy --resume with nothing unfinished starts a new release, and says "already runs ... nothing to do" when the revision is already live (use --force).
• In artifact mode the only build step is the guarded composer install; the database steps still run on the target.
• Shared: wp-config.php (file), wp-content/uploads (dir); writable: wp-content/{uploads,cache,upgrade,languages}.

Rehearsing on the sandbox

govard sandbox up gives a disposable target with wp-cli, a MySQL client, the usual PHP extensions and mariadb + redis-server, so a deploy can be rehearsed with govard deploy --remote sandbox --yes. The origin environment must be running to seed.