Aid Type Controller Documentation

File: /controllers/aidTypeController.php

Purpose: Manages guarantee/aid types for charity subvention programs

Last Updated: December 20, 2024

Total Functions: 5

Lines of Code: ~74

---

📋 Overview

The Aid Type Controller is a simple CRUD (Create, Read, Update, Delete) module that manages guarantee types for charity aid programs. These types categorize different forms of assistance or guarantee requirements for beneficiaries. It provides:

• • Basic aid type management (add, edit, delete, list)
• • Soft delete functionality with audit trails
• • AJAX search for dropdown populations
• • Simple form-based operations
• • User tracking for all changes

Primary Functions

• ✅ Create new aid types
• ✅ Edit existing aid types
• ✅ Soft delete aid types
• ✅ List all active aid types
• ✅ AJAX search for dropdown integration
• ✅ Audit trail with user and timestamp tracking

Related Controllers

• • beneficiariesController.php - Uses aid types for subvention
• • subventionController.php - Aid/payment processing
• • charityController.php - Charity management

---

🗄️ Database Tables

Primary Table (Direct Operations)

🔑 Key Functions

1. Default Action - Add Aid Type Form

Location: Line 7

Purpose: Display simple add form for new aid types

Process Flow:

1. Display header template

2. Display add form (aidtypesview/add.html)

3. Display footer template

Template: Simple form with single name field

---

2. show - List Aid Types

Location: Line 11

Purpose: Display all active aid types in a list/table format

Function Signature:

$aidtypes = R::findAll('guaranteetype','del < 2');

Process Flow:

1. Load all active aid types (del < 2)

2. Assign to template variable

3. Display listing template (aidtypesview/show.html)

Data Structure: Array of aid type objects with full details

---

3. edit - Edit Aid Type Form

Location: Line 17

Purpose: Load and display aid type editing form

Function Signature:

$id = filter_input(INPUT_GET, 'id');
$aidtypes = R::load('guaranteetype', $id);

Process Flow:

1. Extract ID from GET parameter

2. Load aid type record by ID

3. Assign to template variable

4. Display edit template (aidtypesview/edit.html)

Security: No permission checking - relies on URL parameter validation

---

4. savedata - Save Aid Type Data

Location: Line 24

Purpose: Create new or update existing aid type

Function Signature:

$name = filter_input(INPUT_POST, 'name');
$id = filter_input(INPUT_POST, 'id');

Process Flow:

1. Extract name and ID from POST data

2. If new record (no ID):

- Create new guaranteetype bean

- Set del = 0 (active status)

- Set addtoday = current timestamp

- Set adduserid = current user ID

- Initialize delete fields as empty

3. If updating (has ID):

- Load existing record by ID

- Set del = 1 (updated status)

- Set updatetoday = current timestamp

- Set updateuserid = current user ID

4. Set name field

5. Store record

6. Redirect to show page on success/error

Audit Trail Fields:

• • addtoday, adduserid - Creation tracking
• • updatetoday, updateuserid - Update tracking
• • deltoday, deluserid - Deletion tracking

Error Handling: Redirects to appropriate page on exception

---

5. delete - Soft Delete Aid Type

Location: Line 47

Purpose: Mark aid type as deleted (soft delete)

Function Signature:

$id = filter_input(INPUT_GET, 'id');

Process Flow:

1. Extract ID from GET parameter

2. Load aid type record by ID

3. Set del = 2 (soft deleted status)

4. Set deltoday = current timestamp

5. Set deluserid = current user ID

6. Store updated record

7. Redirect to show page

Note: This is true soft delete - record remains in database but marked as deleted

---

6. aidtypes - AJAX Search

Location: Line 55

Purpose: Provide searchable aid type data for AJAX dropdowns

Function Signature:

$name = $_POST['searchTerm'];

Process Flow:

1. Extract search term from POST data

2. Query active aid types matching search term

3. Format results as JSON array for dropdown consumption

4. Return JSON response

Query Pattern:

SELECT id, name as name
FROM guaranteetype 
WHERE del < 2 and name LIKE '%{searchTerm}%' 
LIMIT 50

Response Format:

[
  {"id": 1, "text": "Financial Guarantee"},
  {"id": 2, "text": "Property Guarantee"},
  ...
]

Usage: Integrated with Select2 or similar dropdown libraries

---

🔄 Workflows

Workflow 1: Create New Aid Type

---

Workflow 2: Edit Existing Aid Type

---

Workflow 3: Soft Delete Aid Type

---

🌐 URL Routes & Actions

Add Aid Type (do= empty):

• • No parameters required

Show Aid Types (do=show):

• • No parameters required

Edit Aid Type (do=edit):

• • id - Aid type ID (GET parameter)

Save Aid Type (do=savedata):

• • name - Aid type name (POST parameter)
• • id - Aid type ID for updates (POST parameter, optional)

Delete Aid Type (do=delete):

• • id - Aid type ID (GET parameter)

AJAX Search (do=aidtypes):

• • searchTerm - Search string (POST parameter)

---

🧮 Data Management Features

Soft Delete System

// Deletion status levels:
// del = 0: Active (new records)
// del = 1: Updated (edit mode)  
// del = 2: Soft deleted
// del < 2: Active filter for queries

Audit Trail System

// Creation tracking
$aidtypes->addtoday = date("Y-m-d H:i:s");
$aidtypes->adduserid = $_SESSION['userid'];

// Update tracking  
$aidtypes->updatetoday = date("Y-m-d H:i:s");
$aidtypes->updateuserid = $_SESSION['userid'];

// Deletion tracking
$tables->deltoday = date("Y-m-d H:i:s");
$tables->deluserid = $_SESSION['userid'];

Simple Validation

• • Basic input filtering through filter_input()
• • No duplicate name checking (unlike some other controllers)
• • No complex business rules

---

🔒 Security & Permissions

Input Sanitization

// All inputs filtered through filter_input
$name = filter_input(INPUT_POST, 'name');
$id = filter_input(INPUT_POST, 'id');

Access Control

• • No explicit permission checking implemented
• • Relies on session-based authentication
• • URL parameter validation through filter_input()

Potential Security Concerns

1. No permission verification - Any authenticated user can manage aid types

2. No duplicate checking - Could create duplicate aid type names

3. No referential integrity check - Deleting aid types used by subventions

---

📊 Performance Considerations

Database Optimization

1. Recommended Indexes:

- guaranteetype(del) - For active record filtering

- guaranteetype(name) - For search functionality

- guaranteetype(id, del) - For load operations

2. Query Patterns:

- Simple queries with single table operations

- No complex joins or subqueries

- LIMIT 50 on search to prevent large result sets

Memory Usage

• • Very lightweight operations
• • Single record operations for most functions
• • Limited result sets in AJAX searches

---

🐛 Common Issues & Troubleshooting

1. Duplicate Aid Type Names

Issue: Multiple aid types with same name created

Cause: No duplicate checking in save function

Solution: Add duplicate validation:

$existing = R::count('guaranteetype', 'name = ? AND del < 2 AND id != ?', [$name, $id]);
if ($existing > 0) {
    // Handle duplicate
}

2. Referential Integrity Violations

Issue: Deleting aid types that are still referenced by subventions

Cause: No foreign key constraint checking

Solution: Check references before delete:

$references = R::count('subvention', 'guarantee_type_id = ? AND del < 2', [$id]);
if ($references > 0) {
    // Prevent deletion or cascade
}

3. Missing Audit Information

Issue: Records show blank user/date information

Cause: Session not properly initialized

Debug: Check session userid is set:

var_dump($_SESSION['userid']);

---

🧪 Testing Scenarios

Test Case 1: Basic CRUD Operations

1. Create new aid type with name "Test Guarantee"
2. Verify appears in listing
3. Edit name to "Modified Guarantee" 
4. Verify update appears correctly
5. Delete aid type
6. Verify no longer appears in active listing

Test Case 2: AJAX Search Functionality

1. Create several aid types with different names
2. Test AJAX search with partial matches
3. Verify JSON response format correct
4. Test search limits (50 records max)
5. Test empty search terms

Test Case 3: Audit Trail Verification

1. Create aid type and check addtoday/adduserid
2. Edit aid type and check updatetoday/updateuserid  
3. Delete aid type and check deltoday/deluserid
4. Verify all timestamps and user IDs correct

---

🔗 Integration Points

Used By Other Controllers

// In beneficiariesController.php Excel import:
$guarantee_type_id = $rowData[$col]; // References guaranteetype.id

// In subvention management:
// References guaranteetype.id in subvention.guarantee_type_id

Template Integration

<!-- In dropdown forms -->
<select name="guarantee_type_id">
  <!-- Populated via AJAX search -->
</select>

API Endpoints

• • do=aidtypes provides JSON data for frontend dropdowns
• • Used by Select2 and similar dropdown enhancement libraries

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • beneficiariesController.md - Main beneficiary management
• • subventionController.php - Aid assignment and payment processing
• • Database Schema Documentation - Table relationships

---

💡 Improvement Recommendations

1. Add Duplicate Validation

// In savedata() function
$existing = R::count('guaranteetype', 'name = ? AND del < 2 AND id != ?', [$name, $id ?: 0]);
if ($existing > 0) {
    header("location:aidTypeController.php?error=duplicate");
    return;
}

2. Add Referential Integrity Checks

// Before deletion
$references = R::count('subvention', 'guarantee_type_id = ? AND del < 2', [$id]);
if ($references > 0) {
    header("location:aidTypeController.php?error=in_use");
    return;
}

3. Improve Error Handling

// Add specific error messages and validation
// Use JSON responses for AJAX operations
// Add client-side validation

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur