Price Offers Controller Documentation

File: /controllers/priceoffersController.php

Purpose: Manages price quotations, offers to customers, and promotional pricing proposals

Last Updated: December 19, 2024

Total Functions: 4

Lines of Code: 488

---

📋 Overview

The Price Offers Controller manages the creation, editing, and tracking of price quotations and offers sent to customers. It handles:

• • Creating detailed price quotations with multiple products
• • Managing offer conditions and terms
• • Client-specific or general offers
• • Product-based offers with descriptions and quantities
• • Arabic number conversion for professional presentation
• • Offer serial number generation and tracking
• • Integration with product and client management

Primary Functions

• ✅ Create comprehensive price offers/quotations
• ✅ Display all offers with calculated totals
• ✅ Edit existing offers with full product details
• ✅ Update offers and associated conditions
• ✅ Delete offers and related data
• ✅ Generate unique serial numbers for offers
• ✅ Convert amounts to Arabic written format
• ✅ Handle both existing and new client offers

Related Controllers

• • clientController.md - Customer management for offers
• • productController.md - Product details and pricing
• • sellbillController.md - Convert offers to sales
• • programsettingsController.md - Currency and system settings
• • supplierController.md - Cost analysis for pricing
• • buyBillController.md - Product cost information
• • unitController.md - Product units and measurements

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔧 Key Functions

1. add()

Purpose: Create a new price offer with multiple products and conditions

Called By: Form submission with ?do=add

Line: 283

Parameters (via $_POST):

• • newclientname (string) - New client name for non-existing customers
• • oldclientname (int) - Existing client ID
• • clienttype (int) - 0=existing client, 1=new client
• • generalcondition (text) - General terms and conditions
• • introductioncondition (text) - Introduction/header text for offer
• • offerhidden_itr (int) - Number of products in offer
• • totalsellbillprice (float) - Total offer amount
• • offer_sellbillpricenew (float) - Real total after adjustments
• • offerproudctid{N} (int) - Product ID for item N
• • offerproudctname{N} (string) - Product name for item N
• • offerproprice{N} (float) - Unit price for item N
• • prodescrp{N} (text) - Product description for item N
• • offerpronumber{N} (float) - Quantity for item N
• • div_pr_offertotal{N} (float) - Line total for item N

Process Flow:

Business Logic:

1. Client Handling: Supports both existing clients (by ID) and new clients (by name)

2. Serial Generation: Creates unique offer number using getserails()

3. Product Processing: Iterates through products, handles both catalog and free-text items

4. Condition Management: Creates or updates standard terms and conditions

5. Data Validation: Skips empty product entries automatically

Code Example - Client Processing:

if ($clienttype == 0) {
    // Existing client
    $clientname = R::getCell('select clientname from client where clientid = ' . $oldclientname);
    $Offerpricebillprop->clientid = $oldclientname;
    $Offerpricebillprop->clientname = $clientname;
} else {
    // New client
    $Offerpricebillprop->clientid = 0;
    $Offerpricebillprop->clientname = $newclientname;
}

2. show()

Purpose: Display all price offers with totals and client information

Called By: Navigation to ?do=show

Line: Embedded in main controller logic

Process Flow:

Business Logic:

1. Loads all offers using $OfferpricebillpropEx->queryAllExt()

2. Resolves client names (handles both existing and new clients)

3. Calculates grand total of all offers

4. Converts total to Arabic written format for presentation

5. Integrates YouTube help content

Arabic Number Conversion:

$ar_number = new convert_ar($total_of_all, "male");
$arabic_num = $ar_number->convert_number();
$arabic_num .= ' ' . $Programsettingdata->currancy . ' فقط لاغير';

3. edit()

Purpose: Load offer details for editing with full product and condition information

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

Line: Embedded in main controller logic

Parameters (via $_GET):

• • id (int) - Offer ID to edit

Process Flow:

Business Logic:

1. Loads offer header with total amount conversion to Arabic

2. Retrieves client information (existing client name or stores new client name)

3. Loads all products with enhanced details including barcodes

4. Gets current terms and conditions

5. Prepares comprehensive edit form

Product Details Enhancement:

foreach ($allproductdata as $data) {
    $productData = $productDAO->load($data->productid);
    $productName = $productData->productName;
    $data->productName = $productName;
    $data->parcode = $productData->parcode; // Barcode integration
}

4. update()

Purpose: Update existing offer with modified products and conditions

Called By: Form submission with ?do=update

Line: 377

Parameters (via $_POST):

• • editid (int) - Offer ID to update
• • serialno (string) - Offer serial number
• • billdate (date) - Offer date
• • generalconditionId (int) - Condition record ID
• • All same parameters as add() function

Process Flow:

Business Logic:

1. Preserves Key Data: Keeps original serial number and date if provided

2. Clean Slate Approach: Deletes all existing products and re-creates

3. Client Flexibility: Allows changing between existing and new clients

4. Condition Updates: Updates terms and conditions by ID

5. Data Integrity: Ensures all related data stays synchronized

5. getserails()

Purpose: Generate unique serial number for new offers

Called By: add() function internally

Line: 468

Return Value: Unique 8-character serial number (YYYY + 4 random digits)

Process Flow:

Generate Random Number
         ↓
Format: YEAR + 4 digits
         ↓
Check Database for Duplicates
         ↓
If Duplicate: Generate New
         ↓
Return Unique Serial

Business Logic:

1. Creates serial format: Current year + 4 random digits (e.g., "20243847")

2. Checks existing offers to prevent duplicates

3. Regenerates if collision found

4. Ensures unique identification for each offer

Serial Generation Code:

function generateRandomString($length = 4) {
    $newnum = substr(str_shuffle("0123456789"), 0, $length);
    return date("Y") . '' . $newnum;
}

---

🔄 Business Logic Flow

Complete Offer Creation Workflow

Offer Update Process

---

⚠️ Common Issues

1. Product Line Processing Errors

Symptoms: Missing products in offers or incorrect calculations

Causes:

• • Empty product fields not properly skipped
• • Quantity/price type mismatches
• • Product ID resolution failures

Solutions:

• • Validate all numeric inputs before processing
• • Implement proper empty field checking:

if (empty($productid) && empty($offerproudctname)) {
    continue; // Skip empty lines
}

2. Client Name Resolution Issues

Symptoms: Wrong client names showing in offers

Causes:

• • Incorrect client type handling
• • Database query failures
• • Missing client records

Solutions:

• • Always validate client existence before referencing
• • Implement fallback for missing client data
• • Use proper error handling for database queries

3. Serial Number Collisions

Symptoms: Duplicate serial numbers causing database errors

Causes:

• • Insufficient randomization
• • High-volume concurrent offer creation
• • Database constraint violations

Solutions:

• • Implement robust collision detection
• • Use database transactions for serial generation
• • Consider UUID or timestamp-based serials

4. Arabic Number Conversion Failures

Symptoms: "عفوا العدد خارج النطاق" error in offer display

Causes:

• • Very large numbers outside conversion range
• • Invalid numeric formats
• • Library limitations

Solutions:

• • Validate amount ranges before conversion
• • Implement graceful fallback for large amounts
• • Add proper error handling for conversion library

---

🔗 Dependencies

Required Files

• • ../public/impOpreation.php - Core system operations
• • ../public/config.php - Database configuration
• • ../public/include_dao.php - Data access layer
• • ../library/num_to_ar.php - Arabic number conversion library

Required DAOs

• • OfferpricebillDAO.class.php - Offer line items data access
• • Offerpricebill.class.php - Offer line item DTO
• • OfferpricebillMySqlDAO.class.php - MySQL offer operations
• • OfferpricebillMySqlExtDAO.class.php - Extended offer operations
• • OfferpricebillpropDAO.class.php - Offer header data access
• • Offerpricebillprop.class.php - Offer header DTO
• • OfferpricebillpropMySqlDAO.class.php - MySQL offer header operations
• • OfferpricebillpropMySqlExtDAO.class.php - Extended offer header operations
• • OfferpriceconditionDAO.class.php - Conditions data access
• • Offerpricecondition.class.php - Conditions DTO
• • OfferpriceconditionMySqlDAO.class.php - MySQL conditions operations
• • OfferpriceconditionMySqlExtDAO.class.php - Extended conditions operations
• • ProductDAO.class.php - Product data access
• • ClientDAO.class.php - Client data access
• • ProgramsettingsDAO.class.php - System settings access

Template Files

• • priceoffersview/add.html - Offer creation form
• • priceoffersview/show.html - Offers listing display
• • priceoffersview/edit.html - Offer editing form
• • header.html - Standard page header
• • footer.html - Standard page footer
• • succes.html - Success message template
• • error.html - Error message template

JavaScript Dependencies

• • jQuery for form handling and dynamic product rows
• • Custom validation for offer forms
• • AJAX for real-time calculations
• • Print functionality for offer presentation

---

🎯 Integration Points

Product Integration

• • Product Lookup: Real-time product search and selection
• • Pricing: Integration with current product pricing
• • Barcode Support: Product identification via barcodes
• • Inventory Awareness: Check stock levels for offers

Client Integration

• • Existing Clients: Full client database integration
• • New Clients: Ability to create offers for prospects
• • Client History: Track offer history per client
• • Conversion Tracking: Monitor offer-to-sale conversion

Conversion to Sales

• • Quote Acceptance: Convert offers to actual sales orders
• • Pricing Lock: Maintain quoted prices during conversion
• • Product Availability: Verify stock before conversion
• • Terms Transfer: Carry conditions to sales orders

Financial Integration

• • Currency Support: Multi-currency offers
• • Tax Calculations: Apply appropriate tax rates
• • Discount Handling: Support for quantity and promotional discounts
• • Profit Analysis: Calculate profit margins on offers

---

💡 Best Practices

Offer Creation

1. Always validate client information before creating offers

2. Use product catalog whenever possible for accuracy

3. Include detailed descriptions for custom items

4. Set reasonable validity periods for offers

5. Review calculations before finalizing

Data Management

1. Archive old offers regularly for performance

2. Track offer conversion rates for sales analysis

3. Maintain consistent conditions across similar offers

4. Use serial numbers for proper tracking

5. Backup offer data before major updates

Presentation

1. Format amounts professionally with Arabic text

2. Include complete terms and conditions

3. Use company branding consistently

4. Provide clear product descriptions

5. Make offers easy to understand for customers