README

A powerful PHP package for tracking customer delivery statistics across Pathao, Steadfast, and RedX courier services in Bangladesh. Perfect for e-commerce businesses looking to analyze customer ordering patterns and delivery history.

Note: Framework-agnostic fork of shahariar-ahmad/courier-fraud-checker-bd, enhanced to work with any PHP framework.

✨ Key Features

Works with Any PHP Framework: Seamlessly integrates with Laravel, WordPress, CodeIgniter, Symfony, and more
Multiple Courier Support: Track customer delivery statistics across Pathao, Steadfast, and RedX
Phone Number Validation: Built-in validation for Bangladeshi phone numbers
Flexible Configuration: Support for environment variables or direct configuration
Delivery Analytics: Comprehensive success/cancel/total delivery statistics
Error Handling: Graceful error handling with detailed messages
Simple Integration: Easy-to-use API with comprehensive documentation

⚙️ Installation

composer require huzaifaalmesbah/bd-courier-customer-delivery-stats

Requirements:

PHP 7.4 or higher
Guzzle HTTP client (automatically installed)

🔧 Configuration

Option 1: Environment Variables (Recommended)

Add these to your .env file:

# Pathao Credentials
PATHAO_USER=your_pathao_email@example.com
PATHAO_PASSWORD=your_pathao_password

# Steadfast Credentials
STEADFAST_USER=your_steadfast_email@example.com
STEADFAST_PASSWORD=your_steadfast_password

# RedX Credentials
REDX_USER=your_redx_phone@example.com
REDX_PASSWORD=your_redx_password

Option 2: Direct Configuration

use Ham\BdCourier\CustomerDeliveryStats\CourierCustomerStats;

$customerStats = new CourierCustomerStats([
    'pathao_user' => 'your_pathao_email@example.com',
    'pathao_password' => 'your_pathao_password',
    'steadfast_user' => 'your_steadfast_email@example.com',
    'steadfast_password' => 'your_steadfast_password',
    'redx_user' => 'your_redx_phone@example.com',
    'redx_password' => 'your_redx_password',
]);

🚀 Quick Start

<?php
require_once 'vendor/autoload.php';

use Ham\BdCourier\CustomerDeliveryStats\CourierCustomerStats;

// Initialize (will auto-load from environment variables)
$customerStats = new CourierCustomerStats();

// Check customer delivery history across all services
$result = $customerStats->check('01712345678');

print_r($result);

Output Example:

[
    'pathao' => [
        'success' => 5,
        'cancel' => 2,
        'total' => 7
    ],
    'steadfast' => [
        'success' => 3,
        'cancel' => 1,
        'total' => 4
    ],
    'redx' => [
        'success' => 6,
        'cancel' => 2,
        'total' => 8
    ]
]

📱 Phone Number Validation

The package includes built-in validation for Bangladeshi phone numbers:

use Ham\BdCourier\CustomerDeliveryStats\Helpers\PhoneValidator;

// Validate phone number
if (PhoneValidator::isValid('01712345678')) {
    echo "Valid phone number";
}

// Get validation error
$error = PhoneValidator::getValidationError('+8801712345678');
echo $error; // "Invalid Bangladeshi phone number..."

// Sanitize phone number
$clean = PhoneValidator::sanitize('+88 017-1234-5678');
echo $clean; // "01712345678"

// Format with country code
$withCode = PhoneValidator::withCountryCode('01712345678');
echo $withCode; // "+8801712345678"

Validation Rules:

✅ Valid: 01712345678, 01876543219
❌ Invalid: +8801712345678, 02171234567, 1234567890

🛠️ Advanced Usage

Check Individual Courier Services

// Check only Pathao
$pathaoResult = $customerStats->checkPathao('01712345678');

// Check only Steadfast
$steadfastResult = $customerStats->checkSteadfast('01712345678');

// Check only RedX
$redxResult = $customerStats->checkRedX('01712345678');

Error Handling

try {
    $result = $customerStats->check('01712345678');
    
    if (isset($result['pathao']['error'])) {
        echo "Pathao Error: " . $result['pathao']['error'];
    }
    
    if (isset($result['steadfast']['error'])) {
        echo "Steadfast Error: " . $result['steadfast']['error'];
    }
    
    if (isset($result['redx']['error'])) {
        echo "RedX Error: " . $result['redx']['error'];
    }
    
} catch (Exception $e) {
    echo "Configuration Error: " . $e->getMessage();
}

Risk Assessment Example

$result = $customerStats->check('01712345678');

$totalOrders = ($result['pathao']['total'] ?? 0) + ($result['steadfast']['total'] ?? 0) + ($result['redx']['total'] ?? 0);
$totalCancels = ($result['pathao']['cancel'] ?? 0) + ($result['steadfast']['cancel'] ?? 0) + ($result['redx']['cancel'] ?? 0);

if ($totalOrders > 0) {
    $cancellationRate = ($totalCancels / $totalOrders) * 100;
    
    if ($totalOrders < 3) {
        $risk = 'NEW CUSTOMER';
    } elseif ($cancellationRate > 50) {
        $risk = 'HIGH RISK';
    } elseif ($cancellationRate > 25) {
        $risk = 'MEDIUM RISK';
    } else {
        $risk = 'LOW RISK';
    }
    
    echo "Risk Level: $risk (Cancellation Rate: {$cancellationRate}%)";
}

🔌 Framework Integration Examples

Laravel Integration

// In your controller
use Ham\BdCourier\CustomerDeliveryStats\CourierCustomerStats;

class OrderController extends Controller
{
    public function checkCustomer(Request $request)
    {
        $customerStats = new CourierCustomerStats([
            'pathao_user' => env('PATHAO_USER'),
            'pathao_password' => env('PATHAO_PASSWORD'),
            'steadfast_user' => env('STEADFAST_USER'),
            'steadfast_password' => env('STEADFAST_PASSWORD'),
            'redx_user' => env('REDX_USER'),
            'redx_password' => env('REDX_PASSWORD'),
        ]);
        
        $result = $customerStats->check($request->phone);
        
        return response()->json($result);
    }
}

WordPress Integration

// In functions.php or as a plugin
require_once get_template_directory() . '/vendor/autoload.php';

use Ham\BdCourier\CustomerDeliveryStats\CourierCustomerStats;

function check_customer_delivery_stats($phone) {
    $customerStats = new CourierCustomerStats([
        'pathao_user' => get_option('pathao_user'),
        'pathao_password' => get_option('pathao_password'),
        'steadfast_user' => get_option('steadfast_user'),
        'steadfast_password' => get_option('steadfast_password'),
        'redx_user' => get_option('redx_user'),
        'redx_password' => get_option('redx_password'),
    ]);
    
    return $customerStats->check($phone);
}

// Use shortcode: [courier_delivery_stats]
add_shortcode('courier_delivery_stats', function() {
    // Return customer stats form HTML
});

CodeIgniter Integration

// In your controller (CI 3.x)
require_once APPPATH . '../vendor/autoload.php';

use Ham\BdCourier\CustomerDeliveryStats\CourierCustomerStats;

class Customer_stats extends CI_Controller 
{
    public function check() {
        $customerStats = new CourierCustomerStats([
            'pathao_user' => $this->config->item('pathao_user'),
            'pathao_password' => $this->config->item('pathao_password'),
            'steadfast_user' => $this->config->item('steadfast_user'),
            'steadfast_password' => $this->config->item('steadfast_password'),
            'redx_user' => $this->config->item('redx_user'),
            'redx_password' => $this->config->item('redx_password'),
        ]);
        
        $result = $customerStats->check($this->input->post('phone'));
        
        $this->output
            ->set_content_type('application/json')
            ->set_output(json_encode($result));
    }
}

📁 Examples

Check the examples/ directory for complete integration examples:

examples/BasicUsage.php - Basic usage in any PHP project

🧹 Troubleshooting

Common Issues

Missing Configuration
```
Error: Missing required configuration: pathao_user, pathao_password, redx_user, redx_password
```
Solution: Ensure all credentials are set in environment variables or configuration array.
Invalid Phone Number
```
Error: Invalid Bangladeshi phone number. Please use the local format...
```
Solution: Use local BD format like 01712345678 without +88 prefix.
HTTP Request Failed
```
Error: HTTP POST request failed: Connection timeout
```
Solution: Check internet connection and API endpoint availability.
Guzzle HTTP Client Missing
```
Error: Class 'GuzzleHttp\Client' not found
```
Solution: Run composer install to install dependencies.

📝 License

This package is open-source software licensed under the GNU General Public License v3.0 (GPL-3.0).

🔗 Links & Support

GitHub: huzaifaalmesbah/bd-courier-customer-delivery-stats
Packagist: huzaifaalmesbah/bd-courier-customer-delivery-stats
Issues: GitHub Issues
Contact: hi@huzaifa.im
Original Package: shahariar-ahmad/courier-fraud-checker-bd

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📊 Version History

v1.0.0 - Initial release
- Framework-agnostic design
- Support for multiple PHP frameworks
- Comprehensive phone validation
- Enhanced error handling
- Complete documentation and examples

🙏 Credits

This package is a universal, framework-agnostic fork of the original Laravel-specific package:

Original Author: Shahariar Ahmad
Original Package: shahariar-ahmad/courier-fraud-checker-bd
Original Repository: ShahariarAhmad/ShahariarAhmad-CourierFraudCheckerBD---packagist.org

Enhancements in This Version:

✨ Universal Compatibility: Works with any PHP framework
🔧 Framework-Agnostic: No longer depends on Laravel
📱 Enhanced Phone Validation: Improved phone number validation
🛠️ Flexible Configuration: Multiple configuration methods
📚 Comprehensive Examples: Examples for various frameworks

Special thanks to Shahariar Ahmad for the original implementation.

huzaifaalmesbah / bd-courier-customer-delivery-stats

Maintainers

Details