Dollar Earnings Controller Documentation

File: /controllers/dollarEarningsController.php

Purpose: Manages currency exchange transactions with multi-currency support, conversion tracking, and supplier integration

Last Updated: December 20, 2024

Total Functions: 12

Lines of Code: ~779

---

📋 Overview

The Dollar Earnings Controller handles complex multi-currency financial transactions involving currency exchange between different safes/cash registers. It supports currency conversion with dynamic exchange rates, supplier integration for exchange commissions, daily entry accounting, and comprehensive audit trails.

Primary Functions

• ✅ Multi-currency money transfers between safes
• ✅ Dynamic currency conversion with live rates
• ✅ Supplier commission/expense tracking on exchanges
• ✅ Automated daily entry accounting integration
• ✅ Exchange transaction history and reporting
• ✅ Currency factor management and updates
• ✅ Safe balance validation before transactions
• ✅ Comprehensive audit trail and reversal support

Related Controllers

• • cashTransferController.php - Simple cash transfers
• • saveController.php - Safe/cash register management
• • supplierPayedDeptController.php - Supplier payments
• • expensesController.php - Expense management

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action - Add Exchange Form

Location: Line 54

Purpose: Display currency exchange form with safe and currency options

Function Signature:

// Triggered when: empty($do)

Process Flow:

1. Check user permissions and save access rights

2. Load available safes based on user permissions

3. Load currency options

4. Load supplier list for exchange commissions

5. Display exchange form

Permission Logic:

if ($_SESSION['searchinonesave'] == 0) {
    // User can access multiple safes
    if ($_SESSION['saveids'] == 0) {
        $saves = $mySaveEx->queryAllEX2(); // All safes
    } else {
        $queryString = ' and saveid in (' . $_SESSION['saveids'] . ')';
        $saves = $mySaveEx->queryAllEX2($queryString); // Permitted safes
    }
} else {
    // User restricted to specific safe
    $queryString = ' and saveid = ' . $_SESSION['saveid'] . ' ';
    $save = $mySaveEx->queryAllEXOne2($queryString);
}

---

2. add - Process Currency Exchange

Location: Line 282

Purpose: Execute complex multi-currency exchange transaction

Function Signature:

function add()

Process Flow:

1. Validate input parameters and conversion factors

2. Check source safe has sufficient balance

3. Update currency conversion factors

4. Process money transfer between safes

5. Create supplier expense if applicable

6. Generate daily entry accounting records

7. Return validation status and transaction ID

Currency Conversion Logic:

$transfermoneyValueCurr = (float) $_POST['transfermoneyvalueCurr'];
$transfermoneyvalueInCurrencyto = (float) $_POST['transfermoneyvalueCurrSaveTo'];
$cFactorTo = (isset($_POST['cFactorTo']) && !empty($_POST['cFactorTo'])) ? (float) $_POST['cFactorTo'] : 1;
$cFactorFrom = (isset($_POST['cFactorFrom']) && !empty($_POST['cFactorFrom'])) ? (float) $_POST['cFactorFrom'] : 1;

// Update conversion factor if needed
if ($currencyIdSaveTo > 1) {
    $currencyEX->updateConversionFactor($cFactorTo, $currencyIdSaveTo);
}

Balance Validation:

$saveFromValueBefore = $saveData[0];
$saveFromValueafterValid = $saveFromValueBefore - $transfermoneyValueInSaveCurr;
if ($saveFromValueafterValid >= 0) {
    $saveValuebeforeValid = 1; // Transaction allowed
} else {
    $saveValuebeforeValid = 0; // Insufficient funds
}

---

3. show - Display Exchange History

Location: Line 92

Purpose: Show filtered exchange transaction history

Function Signature:

$startDate = $_REQUEST['from'];
$endDate = $_REQUEST['to'];  
$id = (int) $_REQUEST['id'];

Process Flow:

1. Parse date range and ID filters

2. Apply user save permissions to query

3. Execute complex JOIN query for transaction details

4. Display results with safe names and supplier info

Complex Query Structure:

SELECT dollarearnings.*, savefrom.savename as savefromname, saveto.savename as savetoname, supplier.suppliername
FROM dollarearnings 
JOIN save savefrom ON dollarearnings.saveidfrom = savefrom.saveid 
JOIN save saveto ON dollarearnings.saveidto = saveto.saveid
LEFT JOIN supplier ON dollarearnings.supplierid = supplier.supplierid
WHERE savefrom.conditions = 0 and saveto.conditions = 0   
AND permission_filters
ORDER BY id desc

---

4. delete - Reverse Exchange Transaction

Location: Line 656

Purpose: Reverse a currency exchange transaction

Function Signature:

function delete($oldid)

Process Flow:

1. Load original transaction data

2. Reverse the transaction by swapping from/to safes

3. Update safe balances in reverse

4. Reverse supplier debt changes

5. Reverse daily entry accounting records

6. Mark transaction as deleted (conditions = 2)

Reversal Logic:

$saveidFrom = $rowDataold->saveidto;    // Swap source
$saveidTo = $rowDataold->saveidfrom;    // Swap destination  
$transfermoneyValueCurr = $rowDataold->transfermoneyvalueincurrencyto;
$transfermoneyvalueInCurrencyto = $rowDataold->transfermoneyvalueincurrencyfrom;

---

5. getSaveValueAndMins/Plus - Safe Balance Operations

Location: Lines 517-556

Purpose: Safely update safe balances with currency conversion

Function Signatures:

function getSaveValueAndPlus($saveid, $savevaluechanged, $saveConversionFactor = 0)
function getSaveValueAndMins($saveid, $savevaluechanged, $saveConversionFactor = 0)

Process Flow:

1. Load current save balance with row locking

2. Apply currency conversion if needed

3. Calculate new balance (plus/minus)

4. Return transaction data array

Currency Conversion:

if ($saveConversionFactor == 0) {
    $saveConversionFactor = $saveData->conversionFactor;
}
$savevaluechanged = round(($savevaluechanged * $saveConversionFactor), 4);

---

6. affectSupplierWithExpense - Supplier Integration

Location: Line 597

Purpose: Update supplier debt for exchange commissions

Function Signature:

function affectSupplierWithExpense($supplier, $expensevalue, $suppRemainingVal, $dollarEarningId, $expensecomment, $operation)

Process Flow:

1. Validate expense parameters

2. Update supplier debt balance

3. Create supplier debt change record

4. Handle both add and delete operations

Debt Calculation:

if ($operation == 'add') {
    $changeType = 0;
    $processName = 'اضافه حصيلة دولارية على مورد' . $expensecomment;
    $deptAfter = $deptBefore + $suppRemainingVal;
} elseif ($operation == 'del') {
    $changeType = 1;
    $processName = 'حذف حصيلة دولارية على مورد';
    $deptAfter = $deptBefore - $suppRemainingVal;
}

---

🔄 Workflows

Workflow 1: Currency Exchange Transaction

---

🌐 URL Routes & Actions

Add Exchange (do=add):

• • saveidfrom - Source safe ID
• • saveidto - Destination safe ID
• • transfermoneyvalueCurr - Amount in source currency
• • transfermoneyvalueCurrSaveTo - Amount in destination currency
• • cFactorFrom - Source currency conversion factor
• • cFactorTo - Destination currency conversion factor
• • supplierid (optional) - Supplier for commission
• • exvalue (optional) - Commission amount
• • comment - Transaction comment

Show History (do=show):

• • from - Start date
• • to - End date
• • id (optional) - Specific transaction ID

---

🧮 Calculation Methods

Currency Conversion

// Convert to main currency
$transfermoneyValueInMainCurrency = $transfermoneyValueCurr;
if ($cFactorFrom != 1) {
    $transfermoneyValueInMainCurrency = $transfermoneyValueCurr / $cFactorFrom;
}

// Convert from main currency to destination
$transfermoneyvalueInDestCurrency = $transfermoneyValueInMainCurrency;
if ($cFactorTo != 1) {
    $transfermoneyvalueInDestCurrency = $transfermoneyValueInMainCurrency * $cFactorTo;
}

Safe Balance Updates

// Source safe (decrease)
$saveFromValueafter = $saveFromValuebefore - $transfermoneyValueCurr;

// Destination safe (increase)
$saveToValueafter = $saveToValuebefore + $transfermoneyvalueInCurrencyto;

Supplier Debt Updates

$deptAfter = $deptBefore + $suppRemainingVal; // Add commission debt

---

🔒 Security & Permissions

User Save Access Control

if ($_SESSION['searchinonesave'] == 0) {
    // Multiple save access
    if ($_SESSION['saveids'] != 0) {
        $queryString .= ' and ( dollarearnings.saveidfrom in (' . $_SESSION['saveids'] . ') 
                          or dollarearnings.saveidto in (' . $_SESSION['saveids'] . ') ) ';
    }
} else {
    // Single save access
    $queryString .= ' and ( dollarearnings.saveidfrom = ' . $_SESSION['saveid'] . ' 
                      or dollarearnings.saveidto = ' . $_SESSION['saveid'] . ' ) ';
}

Input Validation

$saveidFrom = $_POST['saveidfrom'];
$saveidTo = $_POST['saveidto'];
$exvalue = $_POST['exvalue'];
$cFactorTo = (isset($_POST['cFactorTo']) && !empty($_POST['cFactorTo'])) ? (float) $_POST['cFactorTo'] : 1;

Transaction Safety

• • Database transactions with rollback capability
• • Balance validation before execution
• • Row locking during balance updates

---

🐛 Common Issues & Troubleshooting

1. Currency Conversion Errors

Issue: Incorrect exchange amounts calculated

Cause: Wrong conversion factors or missing currency data

Debug:

SELECT currencyId, conversionFactor FROM currency;
SELECT saveid, currencyId, savecurrentvalue FROM save WHERE saveid IN (?,?);

2. Insufficient Balance Errors

Issue: Transaction rejected due to insufficient funds

Cause: Currency conversion not applied properly in balance check

Debug:

echo "Source Balance: " . $saveFromValueBefore . "<br>";
echo "Amount to Transfer: " . $transfermoneyValueCurr . "<br>";  
echo "After Balance: " . ($saveFromValueBefore - $transfermoneyValueCurr) . "<br>";

3. Accounting Entry Mismatches

Issue: Daily entries don't balance

Cause: Currency conversion in accounting entries

Debug:

SELECT de.entryComment, ded.value as debit, dec.value as credit
FROM dailyentry de
LEFT JOIN dailyentrydebtor ded ON de.dailyentryid = ded.dailyentryid  
LEFT JOIN dailyentrycreditor dec ON de.dailyentryid = dec.dailyentryid
WHERE de.dailyentryid = ?;

---

📊 Performance Considerations

Database Optimization Tips

1. Indexes Required:

- dollarearnings(sysdate, saveidfrom, saveidto)

- save(saveid, currencyId, conditions)

- savedaily(saveid, savedailydate)

- supplier(supplierid, conditions)

2. Query Optimization:

- Use proper JOIN types for optional suppliers

- Index on sysdate for date range queries

- Efficient permission filtering

3. Transaction Management:

- Minimize transaction scope

- Use row locking only when necessary

- Proper rollback handling

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • saveController.php - Safe/cash register management
• • currencyController.php - Currency management
• • supplierController.php - Supplier management
• • dailyentry.php - Accounting entries

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur