# AI Guidelines – ngauge-caterpoint Module

## Module Overview
The ngauge-caterpoint module provides integration with the Caterpoint API for order import and synchronization within NGauge-based applications.

**Stack:**
- PHP 8.4+
- Yii2 Framework ~2.0.0
- yiisoft/yii2-httpclient ~2.0.0

**API Format:**
- Caterpoint API returns XML responses (despite JSON Accept headers)
- Client automatically detects format and normalizes XML → JSON
- Supports xml/json/html/text response types

## Release Workflow

### Version Bumping
Follow standard versioning (v1.0.x):
1. Update `composer.json` (version, branch-alias.stable)
2. Update `CHANGELOG.md` with changes
3. Commit, tag, and push:
   ```bash
   git add -A
   git commit -m "vX.Y.Z - description of changes"
   git tag vX.Y.Z
   git push
   git push origin vX.Y.Z
   ```

### Package Index Update
After pushing a new version, trigger the Statis package manager webhook to update the Composer package index:

```bash
php yii statis-webhook/webhook/trigger
```

Or use programmatically:

```php
use PortalPeople\StatisWebhook\components\StatisWebhookClient;

$client = new StatisWebhookClient([
    'webhookUrl' => 'https://scupuhfsfu.portalpeople.co.uk/webhook/devops',
    'webhookToken' => getenv('STATIS_WEBHOOK_TOKEN'),
]);

$result = $client->triggerFromGit();
```

The module automatically:
- Fetches current git metadata (commit ID, author, message, repo URL)
- Constructs Azure DevOps-style webhook payload
- Posts to Statis endpoint with authentication
- Updates the package index for composer installations

**Important:** Configure the statis-webhook module in your console config with proper authentication token.

## Architecture Guidelines

### HTTP Client Configuration
- Use yii2-httpclient for all external API calls
- Prefer and use `yii\httpclient\Client` over `guzzlehttp\Client`.
- Configure per-request using builder pattern:
  ```php
  $request = $this->client->createRequest()
      ->setMethod('POST')
      ->setUrl($endpoint)
      ->setHeaders($headers)
      ->setOptions(['timeout' => $this->timeout])
      ->setData($data);
  ```
- **Avoid** setting timeout/headers at client-level (not supported by yii2-httpclient)

## Standards Requirement

- Follow PSR-1 and PSR-12 for all PHP files.
- Follow PSR-4 autoloading layout and namespace-to-path alignment.
- Prefer and use `yii\httpclient\Client` over `guzzlehttp\Client`.

## Required Command-Line Validation On File Updates

After any file update, run command-line checks before commit:

```bash
# Lint changed PHP files (or all module PHP files)
find src -type f -name "*.php" -print0 | xargs -0 -n1 php -l

# Style and standards checks
composer lint

# Auto-fix standards issues when possible, then re-run lint
composer lint:fix
composer lint
```

If tests exist in the module, run them as part of the same validation pass.

### Response Format Handling
The module automatically handles multiple response formats:

1. **Format Detection**: `detectResponseFormat()` inspects Content-Type header and payload structure
2. **XML Parsing**: `parseXmlContent()` converts XML to JSON-compatible arrays
3. **Normalization**: `extractOrders()` handles variable payload structures
4. **Debugging**: `getLastResponseFormat()` exposes detected format in API responses

### Error Handling
- Always provide fallback parsing (XML → JSON fallback)
- Log format detection for debugging
- Return sourceFormat in API responses for transparency

### Code Quality
- Run PHPStan before committing (if `phpstan.neon` exists)
- Follow Yii2 conventions (ActiveRecord, dependency injection)
- Use short array syntax `[]` and curly braces for control structures

## Configuration
See [SETTINGS.md](SETTINGS.md) for module configuration options.

## Testing
See [examples/](examples/) for usage examples and test scripts.

## Authentication
Webhook token is stored in environment configuration (not committed to repository).
Contact system administrator for Statis webhook credentials.
