Client Controller Documentation

File: /controllers/clientController.php

Purpose: Complete customer lifecycle management including creation, editing, deletion, and Excel import functionality

Last Updated: December 20, 2024

Total Functions: 12

Lines of Code: ~1,822

---

📋 Overview

The Client Controller is the primary customer management module that handles all customer-related operations in the ERP system. It provides comprehensive functionality for customer creation, modification, deletion, and bulk import operations. The controller integrates with:

• • Customer debt management
• • Daily entry accounting system
• • Store and product associations
• • Government and area classifications
• • Customer type categorization
• • Online store integration
• • Excel import/export capabilities
• • Supplier linkage for special operations

Primary Functions

• ✅ Customer creation with full profile details
• ✅ Customer editing and updates
• ✅ Customer deletion (soft delete)
• ✅ Excel bulk import functionality
• ✅ Customer listing and search
• ✅ Debt balance initialization
• ✅ Accounting integration (daily entries)
• ✅ Geographic classification (government/area)
• ✅ Customer type categorization
• ✅ Special customer features (RFID, discounts, credit limits)
• ✅ Online store synchronization
• ✅ Supplier linking operations

Related Controllers

• • clientdebt.php - Customer debt tracking
• • clientReportsController.php - Customer reports
• • clientPayedDeptController.php - Payment processing
• • sellbillController.php - Sales operations
• • dailyentry.php - Accounting entries

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action - Add Customer Form

Location: Line 190-237

Purpose: Display customer creation form with all required dropdown data

Process Flow:

1. Check user authentication

2. Load reference data:

- All government locations

- All store locations

- Customer types

- Customer areas

- User delegates

- Associated tags

3. Calculate next customer ID

4. Display add form template

Template Variables:

• • $allGovernment - Government dropdown options
• • $stores - Store assignment options
• • $typeClient - Customer type options
• • $allDelegate - Delegate assignment options
• • $allclientarea - Area classification options
• • $allTags - Available customer tags
• • $nextId - Auto-generated next customer ID

---

2. add() - Create New Customer

Location: Line 632-941

Purpose: Process customer creation with full validation and accounting integration

Function Signature:

function add()

Input Processing:

$clientname = $_POST["txtName"];
$clientaddress = $_POST["txtAddress"];
$clientphone = $_POST["txtPhone"];
$clientmobile = $_POST["txtMobile"];
$clientdebt = (float) $_POST["txtDebt"];
$clientareaid = (int) $_POST["clientareaid"];
$clientcode = $_POST["clientcode"];
$debtLimit = $_POST["debtLimit"];

Validation Checks:

1. Name Uniqueness: Prevents duplicate customer names

2. Required Fields: Validates essential customer information

3. Debt Limit: Ensures proper credit limit settings

4. Type Classification: Validates customer type assignments

Process Flow:

1. Extract and validate POST data

2. Check for existing customer with same name

3. Create new client record

4. Process extended customer details

5. Handle online store settings (if enabled)

6. Create initial debt balance entry (if non-zero)

7. Generate accounting entries for debt

8. Process store assignments

9. Handle customer type assignments

10. Process special features (RFID, discounts)

Accounting Integration:

// Create debt balance entry
if ($clientdebt != 0) {
    $clientDeptChange->clientid = $newClientid;
    $clientDeptChange->clientdebtchangeamount = $clientdebt;
    $clientDeptChange->clientdebtchangetype = 0; // Debt increase
    $clientDeptChange->tablename = 'clientController.php';
    $clientDeptChangeDAO->save($clientDeptChange);
}

Return Values:

• • Positive Integer - Success (new client ID)
• • -1 - Error: Duplicate client name
• • -2 - Error: Missing required fields

---

3. addFromExcel() - Bulk Import from Excel

Location: Line 942-1187

Purpose: Import multiple customers from Excel spreadsheet with validation

Function Signature:

function addFromExcel()

Supported File Formats:

• • Excel 2007+ (.xlsx)
• • Excel 97-2003 (.xls)
• • CSV files

Excel Column Mapping:

1. Validate uploaded file format

2. Load Excel data using PHPExcel

3. For each row:

- Extract customer data

- Validate required fields

- Check name uniqueness

- Create customer record

- Handle debt initialization

- Generate accounting entries

4. Track success/failure counts

5. Generate import summary

Error Handling:

try {
    $objPHPExcel = PHPExcel_IOFactory::load($uploadPath);
    $worksheet = $objPHPExcel->getActiveSheet();
    $highestRow = $worksheet->getHighestRow();
    
    for ($row = 2; $row <= $highestRow; ++$row) {
        // Process each customer row
    }
} catch (Exception $e) {
    // Handle file processing errors
}

---

4. show() - Customer Listing

Location: Line 1188-1240

Purpose: Display paginated list of customers with search capabilities

Function Signature:

function show()

Features:

• • Pagination support
• • Search by name, phone, address
• • Sort by various columns
• • Customer type filtering
• • Area-based filtering
• • Active/inactive status filtering

---

5. edit() - Customer Modification

Location: Line 1401+

Purpose: Load customer data for editing and process updates

Function Signature:

function edit()

Process Flow:

1. Load existing customer data

2. Load related information (areas, types, etc.)

3. Pre-populate edit form

4. Process update submission

5. Handle related record updates

6. Update accounting entries if debt changed

---

6. tempdelete() - Soft Delete Customer

Location: Line 1357-1378

Purpose: Deactivate customer without removing historical data

Function Signature:

function tempdelete($clientid)

Process:

$client = $clientDAO->load($clientid);
$client->conditions = 1; // Mark as deleted
$clientDAO->update($client);

---

7. returndelete() - Reactivate Customer

Location: Line 1379-1400

Purpose: Restore previously soft-deleted customer

Function Signature:

function returndelete($clientid)

Process:

$client = $clientDAO->load($clientid);
$client->conditions = 0; // Mark as active
$clientDAO->update($client);

---

🔄 Workflows

Workflow 1: Customer Creation

---

🌐 URL Routes & Actions

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • clientdebt.php - Customer debt tracking
• • clientReportsController.php - Customer reporting

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur