# CLQMS Code Conventions

## PHP Standards
- **Version**: PHP 8.1+
- **Autoloading**: PSR-4
- **Coding Style**: PSR-12 (where applicable)

## Naming Conventions

| Element | Convention | Example |
|---------|-----------|---------|
| Classes | PascalCase | `PatientController` |
| Methods | camelCase | `createPatient()` |
| Properties | snake_case (legacy) / camelCase (new) | `$patient_id` / `$patientId` |
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| Database Tables | snake_case | `patient_visits` |
| Database Columns | PascalCase (legacy) | `PatientID`, `NameFirst` |
| JSON Fields | PascalCase | `"PatientID": "123"` |

## Imports & Namespaces
- Fully qualified namespaces at top of file
- Group imports: Framework first, then App, then external
- Alphabetical order within groups

```php
<?php
namespace App\Controllers;

use CodeIgniter\Controller;
use CodeIgniter\HTTP\ResponseInterface;
use App\Traits\ResponseTrait;
use Firebase\JWT\JWT;
```

## Controller Pattern
Controllers handle HTTP requests, delegate business logic to Models (no DB queries in controllers).

```php
class ExampleController extends Controller
{
    use ResponseTrait;
    protected $model;
    
    public function __construct()
    {
        $this->model = new \App\Models\ExampleModel();
    }
}
```

## Response Format
All API responses use standardized format:
```php
// Success
return $this->respond([
    'status' => 'success',
    'message' => 'Operation completed',
    'data' => $data
], 200);

// Error
return $this->respond([
    'status' => 'failed',
    'message' => 'Error description',
    'data' => []
], 400);
```

## Database Operations
- Use CodeIgniter Query Builder or Model methods
- Use `helper('utc')` for UTC date conversion
- Wrap multi-table operations in transactions

```php
$this->db->transStart();
// ... operations
$this->db->transComplete();

if ($this->db->transStatus() === false) {
    return $this->respond(['status' => 'error', ...], 500);
}
```

## Test Naming Convention
Format: `test<Action><Scenario><ExpectedResult>`
Examples: `testCreatePatientValidationFail`, `testUpdatePatientSuccess`

## HTTP Status Codes
- 200: GET/PATCH success
- 201: POST success
- 400: Validation error
- 401: Unauthorized
- 404: Not found
- 500: Server error

## Legacy Field Naming
Database uses PascalCase: `PatientID`, `NameFirst`, `Birthdate`, `CreatedAt`