Branches Documentation

Branches Controller Documentation

File: /controllers/branchesController.php

Purpose: Manages company branches/locations, branch settings, and branch-related operations

Last Updated: December 19, 2024

Total Functions: 6

Lines of Code: 262

---

📋 Overview

The Branches Controller manages the company's physical branches and locations in the ERP system. It handles:

Primary Functions

Related Controllers

---

🗄️ Database Tables

Primary Tables (Direct Operations)

Table NamePurposeKey Columns
**branch**Branch master databranchId, branchName, nameEn, phone, mobile, email, branchAddress, addressEn, branchTaxNo, logo, status, createdAt, updatedAt
### Reference Tables

Table NamePurposeRelationship
**youtubelink**Associated video contentReferenced for branch marketing
**user**Branch employeesUsers assigned to specific branches
**store**Branch warehousesEach store belongs to a branch
**buybill**Purchase operationsbuybill.branchid references branch
**sellbill**Sales operationssellbill.branchid references branch
### File Storage

DirectoryPurposeFile Types
**../views/default/images/branch_image**Branch logosJPG, PNG, GIF (250x250 px)
---

🔧 Key Functions

1. add()

Purpose: Create a new company branch with all details

Called By: Form submission with ?do=add

Line: 145

Parameters (via $_POST):

Process Flow: 

Form Data Collection
         ↓
Image Upload Processing (250x250px)
         ↓
Branch Object Creation
         ↓
Database Insert
         ↓
Redirect to Success

Business Logic:

1. Collects all branch information from form

2. Sets automatic dates (branchDate, createdAt, updatedAt)

3. Processes logo upload using uploadImages() with 250x250 resize

4. Creates Branch DTO object with all data

5. Inserts into database via BranchDAO

2. show()

Purpose: Display all branches in system listing

Called By: Navigation to ?do=show

Line: 183

Return Value: Array of all branch objects

Process Flow: 

Database Query (queryAll)
         ↓
Return Branch Array
         ↓
Template Assignment
         ↓
Display Branch List

Business Logic:

1. Queries all branches from database

2. Returns complete branch data array

3. Used by template to display branch listing

3. edit()

Purpose: Load branch data for editing form

Called By: Edit link with ?do=edit&id=X

Line: 192

Parameters (via $_GET):

Return Value: Branch object with all data

Process Flow: 

Get Branch ID from URL
         ↓
Load Branch from Database
         ↓
Return Branch Object
         ↓
Populate Edit Form

4. update()

Purpose: Update existing branch information

Called By: Form submission with ?do=update

Line: 202

Parameters (via $_POST):

Process Flow: 

Load Existing Branch
         ↓
Collect Form Data
         ↓
Process Image Update
         ↓
Update Branch Object
         ↓
Database Update
         ↓
Redirect to Success

Business Logic:

1. Loads existing branch to preserve original creation date

2. Updates all modifiable fields

3. Handles logo image update or keeps existing

4. Uses updateImages() for image management

5. Updates updatedAt timestamp automatically

5. delete()

Purpose: Remove branch from system

Called By: Delete action with ?do=delete&id=X

Line: 243

Parameters (via $_GET):

Process Flow: 

Get Branch ID
         ↓
Database Delete
         ↓
Redirect to Success

Business Logic:

1. Hard deletes branch record from database

2. Note: Should check for dependencies before deletion

6. toggleStatus()

Purpose: Toggle branch active/inactive status

Called By: Status toggle with ?do=toggleStatus&id=X

Line: 251

Parameters (via $_GET):

Process Flow: 

Load Branch Record
         ↓
Toggle Status (0↔1)
         ↓
Update Database
         ↓
Redirect to Success

Business Logic:

1. Loads current branch record

2. Toggles status: 1→0 or 0→1

3. Updates record in database

4. Enables/disables branch for operations

---

🔄 Business Logic Flow

Branch Creation Workflow

┌─────────────────┐
Validate Data
- Name required
- Email format
- Phone format
└─────────────────┘
┌─────────────────┐
Process Logo
- Upload file
- Resize 250px
- Save to disk
└─────────────────┘
┌─────────────────┐
Create Branch
- Set dates
- Set status
- Insert DB
└─────────────────┘

Branch Status Management

┌──────────────────────────┐
Load Current Branch
- Get current status
- Validate permissions
└──────────────────────────┘
┌──────────────────────────┐
Toggle Status
- 1 (active) → 0 (off)
- 0 (inactive) → 1 (on)
└──────────────────────────┘
┌──────────────────────────┐
Update Database
- Save new status
- Trigger side effects
└──────────────────────────┘

---

⚠️ Common Issues

1. Image Upload Failures

Symptoms: Logo not displaying after upload

Causes:

Solutions:

2. Branch Deletion Dependencies

Symptoms: Foreign key constraint errors

Causes: Branch has related records in other tables

Solutions:

3. Status Toggle Not Working

Symptoms: Branch status doesn't change

Causes:

Solutions:

---

🔗 Dependencies

Required Files

Required DAOs

Template Files

Image Upload Configuration

---

🎯 Integration Points

Multi-Branch Operations

Many other controllers reference branch data:

Security Considerations

Performance Notes