gdc_cmod/AGENTS.md

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Project Overview

CodeIgniter 4 PHP application for laboratory management (GDC CMOD). Handles specimen tracking, request validation, and result management with role-based access control. SQL Server database with Firebird legacy patient data.

Tool Usage

Always use Serena MCP tools for anything possible:

• Use serena_find_symbol instead of grep when looking for classes, methods, or functions
• Use serena_search_for_pattern instead of grep for code pattern searches
• Use serena_read_file or serena_replace_content instead of Read/Edit tools
• Use serena_find_referencing_symbols to find where symbols are used
• Use serena_replace_symbol_body or serena_insert_after_symbol for code modifications
• Only use Bash for shell commands (git, composer, php, etc.)

Commands

# Run all tests
composer test
./vendor/bin/phpunit

# Run single test file
./vendor/bin/phpunit tests/unit/HealthTest.php

# Run single test method
./vendor/bin/phpunit tests/unit/HealthTest.php --filter testIsDefinedAppPath

# Development server
php spark serve

# List all routes
php spark list

# Create controller/model
php spark make:controller Admin
php spark make:model User

PHP Standards

• PHP 8.1+ features (typed properties, match expressions)
• Always declare return types for public methods
• No comments unless explaining complex logic
• Use esc() when outputting user data in views

Naming Conventions

Type	Convention	Example
Classes	PascalCase	Admin, UserController
Methods/Variables	camelCase	getUsers(), $userId
Constants	UPPER_SNAKE_CASE	DB_HOST
Database tables	UPPER_SNAKE_CASE	GDC_CMOD.dbo.USERS
Views	lowercase_underscores	admin/index.php

Role-Based Access Control

Role ID	Name	Route Prefix
0	Superuser	/superuser
1	Admin	/admin
2	Lab	/lab
3	Phlebo	/phlebo
4	CS	/cs

// Single role
['filter' => 'role:1']
// Multiple roles
['filter' => 'role:1,2']

Controller Patterns

namespace App\Controllers;

class Admin extends BaseController {
    public function index() { }
}

// API Controllers use ResponseTrait
use App\Controllers\BaseController;
use CodeIgniter\API\ResponseTrait;

class Users extends BaseController {
    use ResponseTrait;
    protected $db;

    public function __construct() {
        $this->db = \Config\Database::connect();
        helper(['url', 'form', 'text']);
    }
}

Database Operations

$this->db = \Config\Database::connect();

// Parameterized queries only
$query = $this->db->query("SELECT * FROM table WHERE id = ?", [$id]);
$row = $query->getRowArray();
$results = $query->getResultArray();

// Transactions
$this->db->transBegin();
try {
    $this->db->query("INSERT INTO ...", [$data]);
    $this->db->transCommit();
} catch (\Throwable $e) {
    $this->db->transRollback();
}

Request/Response Patterns

// GET input
$date1 = $this->request->getVar('date1') ?? date('Y-m-d');

// POST JSON
$input = $this->request->getJSON(true);

// JSON response
return $this->respond(['data' => $results]);
return $this->response->setJSON(['message' => 'Success']);

// View response
return view('admin/index', $data);

// Redirect with errors
return redirect()->back()->with('errors', ['key' => 'message']);

Session Structure

session()->set([
    'isLoggedIn' => true,
    'userid' => (string) $user['USERID'],
    'userroleid' => (int) $user['USERROLEID'],
    'userrole' => (string) $role,
]);

Validation Endpoints

• POST /api/{resource}/validate/{id} - validate a record
• DELETE /api/{resource}/validate/{id} - unvalidate a record

Security

• Use parameterized queries (never interpolate directly)
• Hash passwords with password_hash() / password_verify()
• Validate and sanitize all input before use

Database Schema

• Primary: SQL Server (GDC_CMOD.dbo)
• Legacy: Firebird (GLENEAGLES via ODBC)
• No CI4 Models - raw SQL queries via Database::connect()

Dual-Level Validation

Validation requires 2 different users:

1. First: ISVAL1=1, VAL1USER, VAL1DATE
2. Second (different user): ISVAL2=1, VAL2USER, VAL2DATE