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:

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

```json
{
  "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:

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

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

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

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

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