# AI Guideline - ngauge-shippingcosts

## Purpose

This is a simple no-API Yii2 module scaffold for NGauge.

## Coding Conventions

- Use PHP 8.4+ compatible syntax.
- Use Yii2 controller/action naming conventions.
- Keep business logic in services; keep controllers thin.
- Use short array syntax `[]` and brace control structures.

## 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`.
- Keep methods small and single-purpose where practical (SOLID-friendly).
- Prefer strict, explicit typing where compatible with the module baseline.
- Use PHPCS as the source of truth for style compliance (`phpcs.xml.dist`).

## 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.

## Suggested Structure

- `src/controllers`: route endpoints and page actions
- `src/models`: forms/domain models
- `src/services`: business logic
- `src/traits`: reusable behaviors
- `src/views`: UI templates

## Quality Checklist

- Add validation rules for user input models.
- Add basic logging for non-trivial operations.
- Add README and CHANGELOG updates for released changes.
