clqms-be/.serena/memories/style_and_conventions.md

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.