claude-websimple-devops/references/wp-composer.md

WP Composer

Use this skill for Composer-based dependency management in Websimple WordPress projects.

Context

Websimple manages WordPress plugins and themes with PHP Composer.

Private Websimple Composer packages are served by Satis at:

• https://satis.ledevsimple.ca

For WordPress project conventions such as slug, local path, local URL, database name, and repository URL, use references/wp-project.md. For host tooling assumptions, including the composer executable being available in $PATH, use references/websimple-stack.md.

Operating guidance

• Work from the local project root containing composer.json.
• Prefer read-only inspection commands before making dependency changes.
• Inspect composer.json and composer.lock directly when answering dependency questions.
• Use Composer commands through the host composer executable unless a task explicitly requires container context.
• Treat dependency changes as project code changes: inspect the resulting composer.json and composer.lock, then run a small verification command.
• Ensure wp-config.php loads Composer vendor libraries when a project uses Composer.
• Composer-managed WordPress plugins/themes should be ignored by Git. Some projects also have project-specific plugins/themes committed with the WordPress project; do not delete or overwrite source-controlled plugins/themes when repairing Composer-managed dependencies.

Common read-only checks

Use these before changing dependencies:

composer validate --no-check-all
composer show
composer show vendor/package
composer outdated --direct
composer why vendor/package
composer why-not vendor/package:^1.2

Use composer validate --no-check-all by default because existing Websimple WordPress projects may intentionally use "*" version constraints for WordPress plugins/themes, and plain composer validate complains about unbound constraints.

Package repositories

Composer projects should have Composer repository entries for both Satis (private repository) and WPackagist (official WordPress package repository).

The repositories section of composer.json should include:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://satis.ledevsimple.ca"
    },
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    }
  ]
}

Do not assume every project already has these repositories configured. Check composer.json first.

Repository priority order matters: check Websimple Satis first, then WPackagist. Private Websimple packages should win over public package sources when names overlap.

Dependency changes

When asked to add, update, or remove a WordPress plugin/theme package:

1. Confirm the target project path using references/wp-project.md conventions.
2. Inspect composer.json and composer.lock.
3. Verify package resolution priority before adding or updating packages: Websimple Satis first, then WPackagist.
4. Run the smallest Composer command that performs the requested change.
5. Inspect the diff for composer.json and composer.lock.
6. Run composer validate --no-check-all after the change.

Examples:

composer require vendor/package:^1.2
composer update vendor/package --with-dependencies
composer remove vendor/package
composer validate --no-check-all

Ask before running broad updates such as composer update without package names.

WordPress Composer autoload

When a WordPress project uses Composer, ensure wp-config.php contains this Composer autoloader guard so WordPress can load Composer-managed vendor libraries:

if ( file_exists( __DIR__ . '/vendor/autoload.php' ) ) {
 require_once __DIR__ . '/vendor/autoload.php';
}

Add it only if missing, and avoid duplicating equivalent autoload logic.

Place the guard near the top of wp-config.php, after the opening <?php and any file header/comments, before WordPress settings/constants and before this line:

require_once ABSPATH . 'wp-settings.php';

This keeps Composer classes available to project configuration and WordPress bootstrap code.

Plugins/themes integrity check

Composer-based WordPress projects can drift when a plugin/theme installed under wp-content/plugins or wp-content/themes no longer matches the version/source recorded in composer.lock (for example after a WordPress dashboard update, manual file edits, interrupted install, or broken vendor state).

When diagnosing plugin/theme drift:

1. Inspect composer.lock to identify packages installed into wp-content/plugins/* and wp-content/themes/*.
2. Check Git status before touching files so source-controlled project-specific plugins/themes are preserved.
3. Treat Git-ignored Composer-managed plugin/theme directories as disposable install artifacts.
4. Prefer read-only checks first, such as composer install --dry-run when useful, composer show --locked, and direct inspection of installed package metadata when available.
5. If integrity is uncertain, prefer a clean reinstall of Composer-managed plugins/themes from repositories rather than trying to patch files in place.

Safe repair pattern:

composer install --no-interaction --prefer-dist

If a fresh install is required, remove only Composer-managed, Git-ignored plugin/theme directories and reinstall from composer.lock. Do not remove project-specific plugin/theme directories that are tracked by Git.

Before deleting any plugin/theme directory, verify both:

git check-ignore -q wp-content/plugins/example-plugin
git ls-files --error-unmatch wp-content/plugins/example-plugin >/dev/null 2>&1

Only a path that is ignored and not tracked should be considered disposable. Ask before deleting directories, even when they appear disposable.