# Consumer integration snippets

These are the small edits a consumer plugin needs to make to its existing files (in addition to the new files under `examples/consumer/` which copy verbatim).

## `.gitignore` — add

```gitignore
# Synced cross-sell modules (build-time, never committed)
/cross-sell/

# Local secrets used by bin/pull-modules.php
.env
```

`/cross-sell/` matches the `target_dir` in `modules.json`. Change both if you want a different path.

## `.distignore` — add (for plugins that ship to WordPress.org via rsync + zip)

```gitignore
# Never let local .env files leak into the release zip
.env*
```

`.distignore` typically lives at plugin root and feeds an `rsync --exclude-from=` in your release script. **Do NOT** add `cross-sell/` here — synced modules MUST ship in the release zip.

## `release.sh` — wire the sync in

Insert the sync call between `composer install` and any JS build step, so the rsync that copies files into your release zip picks up the synced modules:

```bash
echo "Installing PHP dependencies..."
composer install --no-dev --optimize-autoloader

# --- ADD THIS BLOCK ---
echo "Syncing cross-sell modules..."
php "${ROOT_DIR}/bin/pull-modules.php"
# ----------------------

echo "Installing JS dependencies..."
# ...
```

If your `release.sh` uses `set -e` (recommended), no extra error handling is needed — a failed sync aborts the release.

## Runtime integration (in your main plugin file)

After `composer install`'s autoloader (and before any plugin bootstrap), require the synced loader. **One line.** It loads `registry.php`, discovers every module's `register.php`, and arbitrates winners on `plugins_loaded` priority 0.

```php
// in yourplugin.php main file, immediately after the composer autoloader:
if ( file_exists( __DIR__ . '/cross-sell/loader.php' ) ) {
    require_once __DIR__ . '/cross-sell/loader.php';
}
```

The `file_exists()` guard makes this a graceful no-op on a fresh clone (before the dev has run `php bin/pull-modules.php`). The plugin still loads; cross-sell modules just don't.

Do **not** manually `require` each module's `init.php` — that bypasses the Registry's version arbitration. If two consumer plugins both manually-require their bundled copies, you get a class redeclaration fatal. Always go through `loader.php`.

## CI setup (GitHub Actions example)

```yaml
- name: Build release
  env:
    GITHUB_TOKEN: ${{ secrets.CROSS_SELL_TOKEN }}
  run: ./release.sh
```

Note: avoid the literal name `GITHUB_TOKEN` if you want to bypass GitHub's auto-injected one — use a different secret name and remap via `env:` as above.