# WHMCS module upgrades

Upgrade paths for `integrations/whmcs` server and addon modules alongside GameCloud API releases.

## Version compatibility

Check release notes for minimum pairs:

| GameCloud API | Server module | Addon module |
|---------------|---------------|--------------|
| 1.0.x | 1.0.x | 1.0.x |
| 1.1.x | 1.1.x | 1.1.0+ (SQL migrations) |

Module metadata declares `APIVersion` in `hexagamecloud_MetaData()`.

## Upgrade order

1. **GameCloud API** — deploy new control plane ([upgrades](../../operations/upgrades.md))
2. **Database migrations** — addon SQL in `modules/addons/hexagamecloud/sql/upgrade-*.sql`
3. **WHMCS addon module** — copy files, run upgrade hook
4. **WHMCS server module** — copy files (usually no DB change)
5. **Verify** — dashboard health, test suspend/unsuspend

Never upgrade WHMCS modules before the API when release notes specify API-first ordering.

## Addon SQL migrations

WHMCS runs `hexagamecloud_upgrade()` on version bump. Manual apply if needed:

```bash
mysql whmcs < integrations/whmcs/modules/addons/hexagamecloud/sql/upgrade-1.1.0.sql
```

Back up WHMCS database before upgrade.

## File deployment

```bash
# From packaging script output or git
cp -r integrations/whmcs/modules/addons/hexagamecloud /path/to/whmcs/modules/addons/
cp -r integrations/whmcs/modules/servers/hexagamecloud /path/to/whmcs/modules/servers/
cp integrations/whmcs/hooks/hexagamecloud.php /path/to/whmcs/includes/hooks/
```

Clear WHMCS template cache if admin UI looks stale.

## Zero-downtime considerations

- Running game servers unaffected by module file update
- Brief API restart during GameCloud upgrade may delay WHMCS module calls — retry logic in `ApiClient.php` handles transient 502
- Place WHMCS in maintenance mode only if API breaking change requires it

## Rollback

1. Restore previous module files from backup
2. Roll back GameCloud images if API incompatible
3. Restore WHMCS DB if SQL migration ran

Product mappings table is forward-compatible unless release notes say otherwise.

## Packaging

```bash
cd integrations/whmcs/packaging
./build-package.sh
```

Distribute ZIP to production WHMCS via change-controlled deploy.

## Related

- [Installation](installation.md)
- [Troubleshooting](troubleshooting.md)
- [Control plane upgrades](../../operations/upgrades.md)