Bind Controller Documentation

File: /controllers/bind.php

Purpose: Employee cash custody and bond management with accounting integration

Last Updated: December 20, 2024

Total Functions: 4

Lines of Code: ~432

---

📋 Overview

The Bind Controller manages employee cash custody and bond transactions within the ERP system. It handles:

• • Employee cash advance management (custody/bond system)
• • Cash safe vs bank account funding sources
• • Automated double-entry accounting integration
• • Employee custody account management in chart of accounts
• • Check and cash transaction tracking
• • Daily entry generation for accounting records
• • Transaction reversal and modification support

Primary Functions

• ✅ Create new employee custody transactions
• ✅ Support both cash safe and bank account sources
• ✅ Generate automatic accounting entries (double-entry)
• ✅ Create employee custody accounts in chart of accounts
• ✅ Handle check payments with beneficiary tracking
• ✅ Update and modify existing transactions
• ✅ Reverse accounting entries on updates
• ✅ Validate employee and funding source data

Related Controllers

• • employeeController.php - Employee management
• • saveController.php - Cash safe management
• • bankaccountController.php - Bank account operations
• • dailyentry.php - Accounting entry management

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action / Add Form - Empty do

Location: Line 122

Purpose: Display form for creating new employee custody transaction

Process Flow:

1. Load active employees for dropdown

2. Load available cash safes

3. Load bank data for bank selection

4. Display bindview/add.html template

Template Variables:

• • $employees - Active employee list
• • $saves - Available cash safes
• • $bankData - Bank master data

---

2. add() - Create New Custody Transaction

Location: Line 140 (route), Line 333 (function)

Purpose: Process new employee custody transaction with accounting integration

Form Parameters:

$employee = $_POST["employee"];      // Employee ID
$bindtype = $_POST["bindtype"];      // 1 = Cash safe, 2 = Bank
$save = $_POST["save"];              // Cash safe ID (if bindtype = 1)
$saveValue = $_POST["saveValue"];    // Cash amount (if bindtype = 1)
$bank = $_POST["bank"];              // Bank ID (if bindtype = 2)
$account = $_POST["account"];        // Bank account ID (if bindtype = 2)
$ckekNo = $_POST["ckekNo"];         // Check number (if bindtype = 2)
$benefitName = $_POST["benefitName"]; // Check beneficiary (if bindtype = 2)
$ckekValue = $_POST["ckekValue"];    // Check amount (if bindtype = 2)

Process Flow:

1. Validate form inputs based on transaction type

2. Create new bind record with transaction details

3. Set system fields (userid, date, deleted = 0)

4. Insert record and get new bind ID

5. Call saveDailyEntry() for accounting integration

6. Redirect to success page

Transaction Types:

• • Type 1 (Cash Safe): Employee receives cash from safe
• • Type 2 (Bank/Check): Employee receives check or bank transfer

---

3. edit() - Display Edit Form

Location: Line 152

Purpose: Load existing transaction for modification

Process Flow:

1. Get bind ID from URL parameter

2. Load existing bind record

3. Load related bank accounts for selected bank

4. Load employees, safes, and banks for dropdowns

5. Display bindview/edit.html with pre-populated data

Key Feature: Dynamically loads bank accounts based on previously selected bank using queryByBankidAndaccountdele().

---

4. update() - Modify Existing Transaction

Location: Line 213 (route), Line 380 (function)

Purpose: Update existing custody transaction with accounting reversal

Process Flow:

1. Load existing bind record by ID

2. Update record with new form values

3. Reverse previous accounting entry using reverseEntryWithItsID()

4. Generate new accounting entry with updated values

5. Update bind record with new daily entry ID

Critical Feature: Automatically reverses the original accounting entry before creating a new one, maintaining accounting integrity.

---

5. saveDailyEntry() - Accounting Integration

Location: Line 247

Purpose: Generate double-entry accounting records for custody transactions

Function Signature:

function saveDailyEntry($value, $bindtype, $employeeId, $id, $bankaccount, $bindId)

Accounting Logic:

DEBIT Side (Employee Custody Account):

// Create or find employee custody account
$accountsTree33 = $accountsTreeDAO->queryByName('عهدة ' . $employee->employeeName);
if (count($accountsTree33) > 0) {
    $treeId3 = $accountsTree33[0]->id;
} else {
    // Create new custody account under parent ID 46
    $treeId3 = addTreeElement('عهدة ' . $employee->employeeName, 46, 3, 0, 1, '', 0, 0);
}

CREDIT Side (Funding Source):

if ($bindtype == 1) {  // Cash Safe
    $mySave = $mySaveDAO->load($id);
    if ($mySave->treeId > 0) {
        $treeId2 = $mySave->treeId;
    } else {
        // Create safe account under parent ID 20
        $treeId2 = addTreeElement($mySave->savename, 20, 3, 0, 1, '', 0, 0);
    }
} else {  // Bank Account
    $bankAccountData = $myBankaccountDAO->load($bankaccount);
    if ($bankAccountData->treeId > 0) {
        $treeId2 = $bankAccountData->treeId;
    } else {
        // Create bank account under parent ID 38
        $treeId2 = addTreeElement("$bankAccountData->accountname / $bankData->bankname", 38, 3, 0, 1, '', 0, 0);
    }
}

Transaction Creation:

$data = insertEntery($dailyEntry, $dailyEntryDebtorArray, $dailyEntryCreditorArray, 1);
$dailyEntryId = $data[1];
$bind->dailyentryid = $dailyEntryId;  // Link back to bind record

---

🔄 Workflows

Workflow 1: Cash Safe Custody Transaction

---

Workflow 2: Bank/Check Custody Transaction

---

🌐 URL Routes & Actions

🧮 Calculation Methods

Chart of Accounts Structure

Double-Entry Accounting

// For cash advance from safe
DEBIT:  Employee Custody Account     $1,000
CREDIT: Cash Safe Account                     $1,000

// For check advance from bank
DEBIT:  Employee Custody Account     $2,500  
CREDIT: Bank Account                          $2,500

Account Linking Logic

// Safes linked to tree with parent ID 20 (Cash accounts)
$treeId2 = addTreeElement($mySave->savename, 20, 3, 0, 1, '', 0, 0);

// Bank accounts linked to tree with parent ID 38 (Bank accounts)
$treeId2 = addTreeElement("$accountname / $bankname", 38, 3, 0, 1, '', 0, 0);

// Employee custody accounts under parent ID 46 (Employee advances)
$treeId3 = addTreeElement('عهدة ' . $employee->employeeName, 46, 3, 0, 1, '', 0, 0);

---

🔒 Security & Permissions

Access Control

include_once("../public/authentication.php");  // Session validation on all actions

Input Validation

$bindId = filter_input(INPUT_GET, "id");      // Sanitize GET parameters
$employee = filter_input(INPUT_POST, "employee"); // Sanitize POST data

Session Management

• • All actions require active user session
• • User ID tracked in bind records (userid field)
• • Date stamps automatically applied (binddate)

Data Integrity

• • Soft deletes only (deleted = 1)
• • Transaction rollback on accounting entry failures
• • Accounting entry reversal before updates

---

📊 Performance Considerations

Database Optimization

1. Indexes Required:

- bind(employeeid, deleted, binddate)

- employee(employeeId, conditions)

- save(saveid, treeId)

- bankaccount(accountid, bankid, treeId)

2. Query Patterns:

- Frequent employee lookups for dropdowns

- Tree ID checks for account linking

- Daily entry insertions with transaction support

3. Chart of Accounts Growth:

- New employee accounts created automatically

- Tree structure may grow large over time

- Consider archiving inactive employee accounts

---

🐛 Common Issues & Troubleshooting

1. Missing Employee Custody Accounts

Issue: Employee transactions fail to create accounting entries

Cause: Chart of accounts structure missing parent account (ID 46)

Fix:

-- Verify parent account exists for employee custody
SELECT * FROM accountstree WHERE id = 46;

-- Create if missing
INSERT INTO accountstree (id, name, parentid, level, isLeaf) 
VALUES (46, 'Employee Custody Accounts', [PARENT_ID], 2, 0);

2. Bank Account Linking Failures

Issue: Bank transactions don't create proper accounting entries

Cause: Bank accounts not linked to chart of accounts

Debug:

-- Check bank account tree linkage
SELECT ba.accountname, ba.treeId, at.name 
FROM bankaccount ba 
LEFT JOIN accountstree at ON ba.treeId = at.id 
WHERE ba.accountid = [ACCOUNT_ID];

3. Transaction Update Errors

Issue: Updates fail or create duplicate accounting entries

Cause: Daily entry reversal function not working

Fix: Verify reverseEntryWithItsID() function exists and works:

-- Check if daily entry was properly reversed
SELECT * FROM dailyentry WHERE dailyentryid = [ENTRY_ID];
SELECT * FROM dailyentrycreditor WHERE dailyentryid = [ENTRY_ID];
SELECT * FROM dailyentrydebtor WHERE dailyentryid = [ENTRY_ID];

4. Form Dropdown Issues

Issue: Employee or bank dropdowns empty

Cause: Active record filtering too restrictive

Debug:

-- Check active employees
SELECT COUNT(*) FROM employee WHERE conditions = 0;

-- Check active banks  
SELECT COUNT(*) FROM bank WHERE conditions = 0;

-- Check active safes
SELECT COUNT(*) FROM save WHERE conditions = 0;

---

🧪 Testing Scenarios

Test Case 1: Cash Safe Transaction

1. Create new employee if needed
2. Create cash safe with positive balance
3. Submit bind form with cash safe option
4. Verify bind record created
5. Check accounting entry generated
6. Confirm employee custody account created
7. Verify safe account linked properly

Test Case 2: Bank Check Transaction

1. Setup bank and bank account
2. Submit bind form with check details
3. Verify check number and beneficiary stored
4. Check bank account tree linkage
5. Confirm accounting entry balances
6. Test check number uniqueness (if required)

Test Case 3: Transaction Update

1. Create initial transaction
2. Note original daily entry ID
3. Update transaction with new amount
4. Verify old entry reversed
5. Confirm new entry created
6. Check bind record updated
7. Verify accounting totals correct

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • dailyentry.md - Accounting entry management
• • employeeController.md - Employee management
• • saveController.md - Cash safe operations
• • bankaccountController.md - Bank account management

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When accounting integration changes or new custody features added