Shipper Companies Controller Documentation

File: /controllers/shippercompaniesController.php

Purpose: Manages shipping companies and their representatives for logistics and delivery operations

Last Updated: December 20, 2024

Total Functions: 8

Lines of Code: 508

---

📋 Overview

The Shipper Companies Controller manages shipping/logistics companies and their representative contacts in the ERP system. It handles:

• • Creating and editing shipping companies
• • Managing company representatives (multiple per company)
• • Dynamic representative management (add/remove via interface)
• • Soft delete functionality (temporary delete/restore)
• • Bulk operations on multiple companies
• • Integration with shipping policies and bills
• • Validation for policy dependencies before deletion

Primary Functions

• ✅ Create new shipping companies with multiple representatives
• ✅ Edit existing companies and their representatives
• ✅ Delete companies (with policy validation)
• ✅ Temporary delete (soft delete)
• ✅ Restore deleted companies
• ✅ View all companies with representatives
• ✅ Bulk operations (delete/restore multiple companies)
• ✅ Representative contact management

Related Controllers

• • sellbillController.php - Sales with shipping integration
• • buyBillController.php - Purchase operations
• • clientController.php - Client management
• • supplierController.php - Supplier management
• • storeController.php - Warehouse management
• • productController.php - Product management
• • currencyController.php - Currency management
• • taxController.php - Tax management
• • userController.php - User management
• • branchesController.php - Branch management
• • programsettingsController.php - System settings
• • shippingFilesController.php - Shipping document management

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔧 Key Functions

1. add() - Create New Shipping Company

Location: Line 257

Purpose: Creates a new shipping company with multiple representatives

Function Signature:

function add()

Parameters (via $_POST):

• • companyName - Shipping company name
• • otherInfo - Additional company information
• • hidden_itr - Number of representatives being added
• • representativeName{n} - Representative names (dynamic, n=1 to hidden_itr)
• • representativePhone{n} - Representative phone numbers
• • otherInfo{n} - Additional representative information

Process Flow:

Code Example:

// Create company first
$myShippercompanies->companyName = $_POST['companyName'];
$myShippercompanies->tempdele = 0; // Active by default
$companyId = $myShippercompaniesRecord->insert($myShippercompanies, $otherInfo);

// Add representatives
for ($h = 1; $h <= $itr; $h++) {
    $representativeName = $_POST['representativeName' . $h];
    $representativePhone = $_POST['representativePhone' . $h];
    
    if (isset($representativeName) && $representativeName != "" && 
        isset($representativePhone) && $representativePhone != "") {
        
        $myRepresentativecompany->companyId = $companyId;
        $myRepresentativecompany->representativeName = $representativeName;
        $myRepresentativecompany->representativePhone = $representativePhone;
        
        $myRepresentativecompanyRecord->insert($myRepresentativecompany, $otherInfo);
    }
}

---

2. show() - Display All Shipping Companies

Location: Line 295

Purpose: Retrieves all shipping companies for display

Function Signature:

function show()

Return Value: Array of all shipping company records

Process Flow:

---

3. deletetemp() - Soft Delete Company

Location: Line 305

Purpose: Temporarily hide shipping company (soft delete)

Function Signature:

function deletetemp($companyId)

Parameters:

• • $companyId - Company ID to soft delete

Return Value: Status message ("success" or error message)

Process Flow:

Code Example:

$myShippercompanies->companyId = $companyId;
$myShippercompanies->tempdele = 1; // Mark as deleted
$myShippercompaniesEx->updateTempdele($myShippercompanies);

---

4. returndelete() - Restore Deleted Company

Location: Line 331

Purpose: Restore temporarily deleted shipping company

Function Signature:

function returndelete($companyId)

Parameters:

• • $companyId - Company ID to restore

Return Value: Status message ("success" or error message)

Process Flow:

---

5. delete() - Permanent Delete with Validation

Location: Line 357

Purpose: Permanently delete shipping company after policy validation

Function Signature:

function delete($companyId)

Parameters:

• • $companyId - Company ID to delete

Return Value: Array [policyValid, statusMessage]

• • policyValid: 0 = can delete, 1 = has policies (cannot delete)
• • statusMessage: Success or error message

Process Flow:

Code Example:

// Check for dependent policies
$policyData = $myPolicyRecord->queryByCompanyId($companyId);

if (count($policyData) > 0) {
    $policyValid = 1;
    $note = "لا يمكن حذف هذه الشركة لوجود بوليصة شحن مرتيطة بها";
} else {
    // Safe to delete
    $myRepresentativecompanyRecord->deleteByCompanyId($companyId);
    $myShippercompaniesRecord->delete($companyId);
    $policyValid = 0;
    $note = "success";
}

return array($policyValid, $note);

---

6. edit() - Load Company for Editing

Location: Line 396

Purpose: Load shipping company and representative data for editing

Function Signature:

function edit($companyId)

Parameters:

• • $companyId - Company ID to edit

Return Value: Array [loadData, representativecompanyData, representativecompanyNum]

• • loadData: Company master data object
• • representativecompanyData: Array of representative records
• • representativecompanyNum: Count of representatives

Process Flow:

---

7. update() - Update Company and Representatives

Location: Line 414

Purpose: Update company information and rebuild representative list

Function Signature:

function update()

Parameters (via $_POST):

• • companyName - Updated company name
• • companyId - Company ID being updated
• • tempdele - Company active status
• • otherInfo - Additional company information
• • hidden_itr - Number of representatives
• • Representative arrays (same as add function)

Process Flow:

⚠️ Important: This function completely replaces all representatives rather than updating individual records.

---

8. executeOperation() - Bulk Operations

Location: Line 458

Purpose: Perform bulk operations on multiple selected companies

Function Signature:

function executeOperation()

Parameters (via $_POST):

• • operation - Operation type (1=temp delete, 2=restore, 3=permanent delete)
• • choosedItem - Array of company IDs to process

Return Value: Sets Smarty variables for result display

Process Flow:

Code Example:

$operationType = $_POST['operation'];
$choosedItemArr = $_POST['choosedItem'];

foreach ($choosedItemArr as $companyId) {
    $shippercompaniesData = $myShippercompaniesRecord->load($companyId);
    $companyName = $shippercompaniesData->companyName;
    
    if ($operationType == '1') {
        // Temp delete
        $note = deletetemp($companyId);
    } elseif ($operationType == "2") {
        // Restore
        $note = returndelete($companyId);
    } elseif ($operationType == "3") {
        // Permanent delete
        $note = delete($companyId);
    }
    
    // Collect output for display
    $outputString .= $companyName . ": " . $result . "<br/>";
}

---

🔄 Business Logic Flow

Complete Company Management Workflow

Representative Management Logic

---

⚠️ Common Issues

1. Policy Dependency Validation

• • Issue: Cannot delete companies with active shipping policies
• • Solution: System checks policy.companyId before allowing deletion
• • User Experience: Clear error message with policy reference
• • Status: ✅ Implemented

2. Representative Management

• • Issue: Update replaces all representatives instead of individual updates
• • Impact: May cause concurrency issues with multiple users
• • Current Behavior: Delete all → Re-insert all
• • Recommendation: Implement individual representative update tracking

3. Bulk Operation Performance

• • Issue: Bulk operations process one by one (not transactional)
• • Impact: Partial failures possible
• • Current Status: Individual try-catch per item
• • Recommendation: Wrap in database transaction

4. Input Validation

• • Issue: Limited server-side validation
• • Current: Basic empty string checks for representatives
• • Missing: Company name uniqueness, phone number format validation
• • Recommendation: Add comprehensive validation layer

---

🔗 Dependencies

Required Files

• • /public/impOpreation.php - Core operations and system utilities
• • /public/config.php - Database and system configuration
• • /public/include_dao.php - All DAO class inclusions
• • /public/authentication.php - User authentication and session management

DAO Classes

• • ShippercompaniesDAO.class.php - Data access interface for companies
• • Shippercompanie.class.php - Company data transfer object
• • ShippercompaniesMySqlDAO.class.php - MySQL implementation for companies
• • ShippercompaniesMySqlExtDAO.class.php - Extended MySQL operations (soft delete)
• • RepresentativecompanyDAO.class.php - Representative data access interface
• • Representativecompany.class.php - Representative data transfer object
• • RepresentativecompanyMySqlDAO.class.php - MySQL implementation for representatives
• • PolicyDAO.class.php - Policy dependency validation
• • YoutubeLinkDAO.class.php - Help system integration

Template Dependencies

• • shippercompaniesview/add.html - Add form template
• • shippercompaniesview/show.html - List view template with bulk operations
• • shippercompaniesview/edit.html - Edit form template
• • header.html, footer.html - Layout templates
• • succes.html, error.html - Status page templates
• • notes2.html - Special notes display for policy conflicts

JavaScript Dependencies

• • Custom validation scripts (customValidation = 1)
• • Shipper-specific UI enhancements (customShipper = 1)
• • Bank and check-related UI features (customBank = 1, customCheck = 1)

---

🎯 Usage Examples

Creating a Shipping Company with Representatives

// POST data for new shipping company
$_POST = [
    'companyName' => 'Express Logistics LLC',
    'otherInfo' => 'Nationwide shipping coverage',
    'hidden_itr' => 3, // 3 representatives
    'representativeName1' => 'John Smith',
    'representativePhone1' => '+1234567890',
    'otherInfo1' => 'Sales Manager',
    'representativeName2' => 'Jane Doe',
    'representativePhone2' => '+1234567891',
    'otherInfo2' => 'Operations Manager',
    'representativeName3' => 'Bob Wilson',
    'representativePhone3' => '+1234567892',
    'otherInfo3' => 'Customer Service'
];

// Controller call: ?do=add
// Result: Company + 3 representatives created

Bulk Operations

// POST data for bulk operations
$_POST = [
    'operation' => '1', // Temp delete
    'choosedItem' => ['1', '3', '5'] // Company IDs
];

// Controller call: ?do=executeOperation
// Result: Companies 1, 3, 5 temporarily deleted

Policy Validation Before Deletion

// Attempt permanent deletion
// GET: ?do=delete&companyId=123

// If policies exist:
// Result: Error page with message
// "لا يمكن حذف هذه الشركة لوجود بوليصة شحن مرتيطة بها"

// If no policies:
// Result: Company and all representatives deleted

---

🔍 Business Rules

1. Company Creation: Must have company name, representatives are optional

2. Representative Validation: Both name and phone required for each representative

3. Soft Delete Priority: Prefer temporary delete over permanent deletion

4. Policy Protection: Cannot permanently delete companies with active policies

5. Bulk Operations: Support mass temporary delete, restore, and permanent delete

6. Representative Management: Complete replacement on update (not individual updates)

7. Status Tracking: tempdele field manages soft delete status (0=active, 1=deleted)

---

Performance Notes:

• • Dynamic representative management via looping (scalable for reasonable numbers)
• • Policy validation adds database query overhead on deletion
• • Bulk operations are not transactional (individual processing)
• • Standard DAO pattern for database operations

Security Notes:

• • Requires authentication for all operations
• • Uses parameterized queries via DAO layer
• • Input sanitization handled by DAO implementations
• • Session validation on each controller action
• • Foreign key validation prevents orphaned policy records