Expenses Type Controller Documentation

File: /controllers/expensesTypeController.php

Purpose: Manages hierarchical expense category system with tree structure, accounting integration, and user group permissions

Last Updated: December 20, 2024

Total Functions: 12+

Lines of Code: ~620

---

📋 Overview

The Expenses Type Controller manages a comprehensive expense categorization system with hierarchical tree structure and accounting chart integration. It provides:

• Hierarchical expense category management with parent-child relationships
• Integration with chart of accounts for financial reporting
• User group-based permission control for category access
• Tree-structured expense type display with visual hierarchy
• Bulk operations for category management
• Save account filtering based on user permissions
• Web API integration support
• Supervision ratio and amount configurations

Primary Functions

✅ Create hierarchical expense categories
✅ Tree-structured category display with indentation
✅ Integration with accounting chart of accounts
✅ User group permission controls
✅ Bulk delete operations with dependency checking
✅ Save account filtering by user permissions
✅ Parent-child relationship management
✅ CRUD operations with JSON API support

Related Controllers

• expensesController.php - General expense management
• expenseexchange.php - Project expense transactions
• accountstree.md - Chart of accounts management
• saveController.php - Save account management

---

🗄️ Database Tables

Primary Tables (Direct Operations)

Table Name	Purpose	Key Columns
expensestype	Expense category hierarchy	expensestypeid, expensestypename, parent, treeId, type, treeType, saveid, addOnlyGroupIds
expenses	Expense transactions	expensestypeid, expensesValue, expensesdate, conditions

### Integration Tables

Table Name	Purpose	Key Columns
accountstree	Chart of accounts	id, name, parent, customName, itemtype
save	Cash registers/safes	saveid, savename, treeId
usergroup	User permission groups	usergroupid, usergroupname

### Reference Tables

Table Name	Purpose	Key Columns
user	System users	userid, username, usergroupid
youtubelink	Tutorial links	youtubelinkid, title, url

---

🔑 Key Functions

1. Default Action - Add Form Display

Location: Line 96

Purpose: Display hierarchical expense type creation form

Process Flow:

1. Build tree-ordered expense type hierarchy

2. Configure save account access based on permissions

3. Load user groups for permission assignment

4. Display form with tree structure

Tree Building:

orderExtepensesTypeParentsAsTree(0); 
$allParents = $dataOrdered;
$smarty->assign("allParents", $allParents);

---

2. add() - Create Expense Type

Location: Line 289

Purpose: Create new expense type with accounting integration

Function Signature:

function add()

Process Flow:

1. Input Processing:

   $name = $_POST['name'];
   $withinsupervision_ratio = $_POST['withinsupervision_ratio'];
   $supervision_ratiotype = $_POST['supervision_ratiotype'];
   $supervision_amount = $_POST['supervision_amount'];
   $parentid = $_POST['parent'];
   $type = (int) $_POST["type"];
   $treeType = (int) $_POST["treeType"];
   $saveid = (int) $_POST["saveid"];
   ```

2. **User Group Processing**:
   ```php
   $addOnlyGroupIds = filter_input(INPUT_POST, 'addOnlyGroupIds', FILTER_DEFAULT, FILTER_REQUIRE_ARRAY);
   $addOnlyGroupIds_str = implode(',', $addOnlyGroupIds);
   ```

3. **Database Insert**:
   ```php
   $id = $expensesTypeDAO->insert($expensesType);
   ```

4. **Chart of Accounts Integration**:
   ```php
   if ($parentid < 1) {
       if ($treeType == 0) $parent = 414;      // Operating expenses
       elseif ($treeType == 1) $parent = 413;  // Administrative expenses  
       elseif ($treeType == 2) $parent = 412;  // Cost of goods sold
   } else {
       $parentData = $expensesTypeDAO->load($parentid);
       $parent = $parentData->treeId;
   }
   $treeId = addTreeElement($name, $parent, 3, 0, 0, '', 0, 0);
   ```

**Tree Type Categories**:
- `treeType = 0` - Operating Expenses (Tree ID 414)
- `treeType = 1` - Administrative Expenses (Tree ID 413)  
- `treeType = 2` - Cost of Goods Sold (Tree ID 412)

---

### 3. **show()** - Display Expense Types
**Location**: Line 351  
**Purpose**: Show hierarchical expense type listing with filtering

**Process Flow**:
1. Build tree-ordered hierarchy for display
2. Apply parent filter if specified
3. Process name-based filtering with tree traversal

**Hierarchy Display**:

php

orderExtepensesTypeParentsAsTree(0);

$allData = $dataOrdered;

$name = $_REQUEST['parent'];

if ($name != '-1') {

$name = ltrim(str_replace("_", " ", $name));

$qname = $expensesTypeExt->queryAllname($name);

} else {

$qname = $allData;

}

---

### 4. **orderExtepensesTypeParentsAsTree()** - Build Tree Structure
**Location**: Line 258  
**Purpose**: Recursively build hierarchical tree display with indentation

**Function Signature**:

php

function orderExtepensesTypeParentsAsTree($parent, $expensestypeid = 0, $level)

**Process Flow**:
1. **Permission-Based Filtering**:
   ```php
   $queryString = '';
   if ($_SESSION['searchinonesave'] == 0) {
       if ($_SESSION['saveids'] != 0) {
           $queryString = ' and (expensestype.saveid = 0 or expensestype.saveid in (' . $_SESSION['saveids'] . '))';
       }
   } else {
       $queryString = ' and expensestype.saveid = ' . $_SESSION['saveid'];
   }
   ```

2. **Recursive Tree Building**:
   ```php
   $result = $expensesTypeExt->getTypesWithoutExpenses(" and expensestype.expensestypeid != $expensestypeid and expensestype.parent = $parent $queryString");
   
   foreach ($result as $type) {
       $type->conditions = $level;
       $preString = str_repeat('_', $level);
       $type->expensestypename = $preString . ' ' . $type->expensestypename;
       array_push($dataOrdered, $type);
       orderExtepensesTypeParentsAsTree($type->expensestypeid, $expensestypeid, $level + 1);
   }
   ```

**Visual Hierarchy Example**:

Operating Expenses

_ Utilities

__ Electricity

__ Water

_ Transportation

__ Fuel

__ Maintenance

Administrative Expenses

_ Office Supplies

_ Professional Services

---

### 5. **update()** - Modify Expense Type
**Location**: Line 425  
**Purpose**: Update expense type with accounting tree synchronization

**Process Flow**:
1. Update expense type record
2. Synchronize with chart of accounts
3. Handle parent relationship changes

**Tree Synchronization**:

php

$oldData = $expensesTypeDAO->load($id);

$treeId = $oldData->treeId;

$getRow = $accountsTreeDAO->load($treeId);

if ($parentid == 0) {

$getRow->parent = 151; // Default parent

} else {

$oldData2 = $expensesTypeDAO->load($parentid);

$getRow->parent = $oldData2->treeId;

}

editTreeElement($getRow);

---

### 6. **executeOperation()** - Bulk Operations
**Location**: Line 375  
**Purpose**: Perform bulk operations on selected expense types

**Process Flow**:
1. Parse selected expense type IDs
2. Execute operation (currently supports delete)
3. Check dependencies for each item
4. Generate operation report

**Bulk Delete Implementation**:

php

$choosedItemArr = $_POST['choosedItem'];

foreach ($choosedItemArr as $expensesTypeId) {

if ($operationType == '1') { // delete

$note = deleteExt($expensesTypeId);

if ($note != "success") {

$expenseTypeData = $expensesTypeDAO->load($expensesTypeId);

$outputString .= $expenseTypeData->expensestypename . ": " . $note . "
";

}

---

### 7. **delete()** - Delete Expense Type with Validation
**Location**: Line 532  
**Purpose**: Delete expense type with dependency checking

**Process Flow**:
1. **Dependency Validation**:
   ```php
   // Check for associated expenses
   $expensesdata = $expensesRecord->queryByExpensestypeid($expensestypeid);
   
   // Check for child categories
   $childCategories = $expensesTypeDAO->queryByParent($expensestypeid);
   
   if (count($expensesdata) > 0 || count($childCategories) > 0) {
       $note = "لا يمكن حذف هذا النوع لأنه مرتبط ببيانات أخرى";
   }
   ```

2. **Safe Deletion**:
   ```php
   $rowDelData = $expensesTypeDAO->load($expensestypeid);
   delTreeElement($rowDelData->expensestypename);
   
   $expensesType->conditions = 1; // Mark as deleted
   $expensesTypeExt->updateConditions($expensesType);
   ```

---

## 🔄 Workflows

### Workflow 1: Hierarchical Expense Type Creation

┌─────────────────────────────────────────────────────────────┐

│ START: Create Expense Type │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 1. Load Form Dependencies │

│ - Build parent hierarchy tree │

│ - Load user groups for permissions │

│ - Configure save account access │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 2. Process Form Input │

│ - Validate expense type name │

│ - Set supervision configurations │

│ - Process user group permissions │

│ - Determine tree type and parent │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 3. Create Database Record │

│ - Insert expense type record │

│ - Generate unique expense type ID │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 4. Chart of Accounts Integration │

│ IF No Parent (parentid = 0): │

│ ├─ Use default tree parent by type │

│ │ ├─ Operating: 414 │

│ │ ├─ Administrative: 413 │

│ │ └─ COGS: 412 │

│ ELSE: │

│ └─ Use parent's tree ID │

│ │

│ - Create tree element in chart │

│ - Link expense type to tree ID │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 5. Finalize Creation │

│ - Update expense type with tree ID │

│ - Return success response │

│ - Redirect to success page │

└─────────────────────────────────────────────────────────────┘

---

### Workflow 2: Tree Structure Display Building

┌─────────────────────────────────────────────────────────────┐

│ START: Build Tree Structure │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 1. Initialize Tree Building │

│ - Set parent = 0 (root level) │

│ - Clear ordered data array │

│ - Set level = 0 │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 2. Build Permission Filter │

│ IF searchinonesave = 0: │

│ IF saveids != 0: │

│ └─ Filter: saveid = 0 OR saveid in (saveids) │

│ ELSE: │

│ └─ Filter: saveid = current saveid │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 3. Recursive Processing │

│ FOR EACH Level: │

│ │ │

│ ├─ Query children of current parent │

│ │ └─ Apply permission filters │

│ │ │

│ ├─ Process each child: │

│ │ ├─ Set hierarchy level │

│ │ ├─ Add indentation prefix │

│ │ │ └─ preString = repeat('_', level) │

│ │ ├─ Update display name │

│ │ └─ Add to ordered array │

│ │ │

│ └─ Recurse for each child: │

│ └─ Call with (childId, level+1) │

└────────────────────┬────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 4. Return Hierarchical Structure │

│ - Complete tree with visual indentation │

│ - Proper parent-child ordering │

│ - Permission-filtered results │

└─────────────────────────────────────────────────────────────┘

---

## 🌐 URL Routes & Actions

| URL Parameter | Function Called | Description |
|---------------|----------------|-------------|
| `do=` (empty) | Default action | Display expense type creation form |
| `do=add` | `add()` | Create new expense type |
| `do=show` | `show()` | Display expense type hierarchy |
| `do=executeOperation` | `executeOperation()` | Bulk operations on selected types |
| `do=edit` | `edit()` | Load expense type for editing |
| `do=update` | `update()` | Update existing expense type |
| `do=delete` | `delete()` | Delete expense type with validation |

### Required Parameters by Action

**Add Expense Type** (`do=add`):
- `name` - Expense type name
- `descripe` - Description (optional)
- `parent` - Parent expense type ID (0 for root)
- `type` - Type classification
- `treeType` - Chart of accounts category (0/1/2)
- `saveid` - Associated save account ID
- `addOnlyGroupIds[]` - User group permissions array

**Show with Filter** (`do=show`):
- `parent` - Parent name filter (optional, "-1" for all)

**Bulk Operations** (`do=executeOperation`):
- `operation` - Operation type ("1" for delete)
- `choosedItem[]` - Array of expense type IDs

**Edit/Update** (`do=edit`, `do=update`):
- `id` - Expense type ID
- Additional parameters same as add for update

---

## 🧮 Calculation Methods

### Tree Path Generation

php

function orderExtepensesTypeParentsAsTree($parent, $expensestypeid = 0, $level) {

// Generate visual hierarchy

$preString = '';

for ($index = 0; $index < $level; $index++) {

$preString .= '_';

}

$type->expensestypename = $preString . ' ' . $type->expensestypename;

}

### Permission Group Processing

php

$addOnlyGroupIds = filter_input(INPUT_POST, 'addOnlyGroupIds', FILTER_DEFAULT, FILTER_REQUIRE_ARRAY);

$addOnlyGroupIds_str = '';

foreach ($addOnlyGroupIds as $value) {

$addOnlyGroupIds_str .= $value . ",";

}

$addOnlyGroupIds_str = rtrim($addOnlyGroupIds_str, ',');

### Chart of Accounts Parent Assignment

php

if ($parentid < 1) {

if ($treeType == 0) $parent = 414; // Operating expenses

elseif ($treeType == 1) $parent = 413; // Administrative expenses

elseif ($treeType == 2) $parent = 412; // Cost of goods sold

} else {

$parentData = $expensesTypeDAO->load($parentid);

$parent = $parentData->treeId;

}

---

## 🔒 Security & Permissions

### User Authentication

php

// Standard authentication check

include_once("../public/authentication.php");

### Save Account Access Control

php

if ($_SESSION['searchinonesave'] == 0) {

if ($_SESSION['saveids'] == 0) {

$saves = $saveDAO->queryAll(); // Access to all

} else {

// Restricted to specific save accounts

$queryString = ' and saveid in (' . $_SESSION['saveids'] . ')';

$saves = $saveEX->queryWithConditionWithQueryString($queryString);

}

} else {

// Single save account mode

$saves = $_SESSION['saveid'];

}

### JSON API Security

php

if (isset($_POST['curlpost']) && $_POST['curlpost'] == 1) {

// API response format

$data = array(

'status' => 1,

'message' => 'تمت العمليه بنجاح',

'message_en' => 'Success',

'id' => $id

);

echo json_encode($data);

} else {

// Web interface redirect

header("location:?do=sucess");

}

### Input Sanitization
- All POST data filtered and validated
- SQL injection prevention via DAO layer
- User group array validation
- Parent-child relationship validation
- Dependency checking before deletion

---

## 📊 Performance Considerations

### Database Optimization Tips
1. **Indexes Required**:
   - `expensestype(parent, conditions)` - For tree traversal
   - `expensestype(saveid)` - For permission filtering
   - `expensestype(expensestypename)` - For name searches
   - `expenses(expensestypeid)` - For dependency checking

2. **Query Optimization**:
   - Recursive tree building can be expensive for deep hierarchies
   - Consider caching tree structure for frequently accessed data
   - Use efficient parent-child queries

3. **Memory Management**:
   - Tree building stores all nodes in memory
   - Consider pagination for very large hierarchies
   - Efficient permission filtering at query level

### Known Performance Issues

sql

-- This recursive query can be slow for deep hierarchies

SELECT * FROM expensestype

WHERE parent = ? AND conditions = 0

ORDER BY expensestypename;

-- Solution: Add composite index

CREATE INDEX idx_parent_conditions ON expensestype(parent, conditions, expensestypename);

---

## 🐛 Common Issues & Troubleshooting

### 1. **Tree Hierarchy Display Problems**
**Issue**: Missing indentation or incorrect ordering  
**Cause**: Recursive function logic errors or missing parent relationships

**Debug**:

php

// Add debugging to tree building

echo "Processing parent: $parent, level: $level
";

print_r($result);

### 2. **Chart of Accounts Integration Errors**
**Issue**: Missing tree IDs or broken account links  
**Cause**: Failed tree element creation or invalid parent IDs

**Debug**:

sql

SELECT et.expensestypeid, et.expensestypename, et.treeId,

at.name as account_name, at.parent

FROM expensestype et

LEFT JOIN accountstree at ON et.treeId = at.id

WHERE et.treeId IS NULL OR at.id IS NULL;

### 3. **Permission Filtering Issues**
**Issue**: Users seeing expense types they shouldn't access  
**Cause**: Incorrect save account filtering or permission logic

**Debug**:

php

// Check user permissions

echo "Search in one save: " . $_SESSION['searchinonesave'] . "
";

echo "Save IDs: " . $_SESSION['saveids'] . "
";

echo "Current save ID: " . $_SESSION['saveid'] . "
";

### 4. **Bulk Operation Failures**
**Issue**: Incomplete bulk deletions or error reporting  
**Cause**: Dependency validation errors or transaction issues

**Debug**:

php

// Enhanced error reporting

foreach ($choosedItemArr as $expensesTypeId) {

try {

$note = deleteExt($expensesTypeId);

echo "ID $expensesTypeId: $note
";

} catch (Exception $e) {

echo "Error deleting $expensesTypeId: " . $e->getMessage() . "
";

}

---

## 🧪 Testing Scenarios

### Test Case 1: Hierarchical Structure Creation

1. Create root level expense type

2. Create child expense types under root

3. Create grandchild types under children

4. Verify tree display shows proper indentation

5. Check chart of accounts integration

### Test Case 2: Permission-Based Filtering

1. Login with restricted save account access

2. Create expense types with different save assignments

3. Verify only permitted types appear

4. Test bulk operations with mixed permissions

### Test Case 3: Dependency Validation

1. Create expense type

2. Create expenses using the type

3. Attempt to delete the type

4. Verify deletion is prevented

5. Test error message display

### Debug Mode Enable

php

// Add at top of controller for debugging

error_reporting(E_ALL);

ini_set('display_errors', 1);

// Debug tree building

function debug_tree_building($parent, $level) {

echo str_repeat(" ", $level) . "Processing parent: $parent at level: $level
";

}

```

---

📚 Related Documentation

• CLAUDE.md - PHP 8.2 migration guide
• expensesController.md - General expense management
• accountstree.md - Chart of accounts management
• userController.md - User management and permissions

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur

📚 ERP Docs

ExpensesType Documentation

Expenses Type Controller Documentation

📋 Overview

Primary Functions

Related Controllers

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action - Add Form Display

2. add() - Create Expense Type

📚 Related Documentation