43 lines
1.8 KiB
Markdown
43 lines
1.8 KiB
Markdown
|
# CLQMS Style and Conventions
|
||
|
|
## PHP and Naming
|
||
|
|
- PHP 8.1+, PSR-4 autoloading (`App\\` => `app/`, `Config\\` => `app/Config/`).
|
||
|
|
- Follow PSR-12 where applicable.
|
||
|
|
- Class names: PascalCase.
|
||
|
|
- Method names: camelCase.
|
||
|
|
- Properties: legacy snake_case and newer camelCase coexist.
|
||
|
|
- Constants: UPPER_SNAKE_CASE.
|
||
|
|
- DB tables: snake_case; many DB columns are legacy PascalCase.
|
||
|
|
- JSON fields in API responses often use PascalCase for domain fields.
|
||
|
|
|
||
|
|
## Controller Pattern
|
||
|
|
- Controllers should handle HTTP concerns and delegate to model/service logic.
|
||
|
|
- Avoid embedding DB query logic directly inside controllers.
|
||
|
|
- Use `ResponseTrait` and consistent JSON envelope responses.
|
||
|
|
|
||
|
|
## Response Pattern
|
||
|
|
- Success: `status=success`, plus message/data.
|
||
|
|
- Error: structured error response with proper HTTP status codes.
|
||
|
|
- Empty strings may be normalized to `null` by custom response behavior.
|
||
|
|
|
||
|
|
## DB and Data Handling
|
||
|
|
- Prefer CodeIgniter Model/Query Builder usage.
|
||
|
|
- Use UTC helper conventions for datetime handling.
|
||
|
|
- Multi-table writes should be wrapped in transactions.
|
||
|
|
- For nested entities/arrays, extract and handle nested payloads carefully before filtering and persistence.
|
||
|
|
|
||
|
|
## Error Handling
|
||
|
|
- Use try/catch for JWT and external operations.
|
||
|
|
- Log errors with `log_message('error', ...)`.
|
||
|
|
- Return structured API errors with correct status codes.
|
||
|
|
|
||
|
|
## Testing Convention
|
||
|
|
- PHPUnit tests in `tests/`.
|
||
|
|
- Test naming: `test<Action><Scenario><ExpectedResult>`.
|
||
|
|
- Typical status expectation: 200 (GET/PATCH), 201 (POST), 400/401/404/500 as appropriate.
|
||
|
|
|
||
|
|
## API Docs Rule (Critical)
|
||
|
|
- Any controller/API contract change must update corresponding OpenAPI YAML files under:
|
||
|
|
- `public/paths/*.yaml`
|
||
|
|
- `public/components/schemas/*.yaml`
|
||
|
|
- optionally `public/api-docs.yaml` if references/tags change
|
||
|
|
- Rebuild docs bundle after YAML updates.
|