sabitahmad/laravel-steadfast

Comprehensive Laravel package for SteadFast Courier API integration with bulk processing, return requests, caching, events, and advanced monitoring

Fund package maintenance!
SabitAhmad

Installs: 8

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 1

pkg:composer/sabitahmad/laravel-steadfast

v2.0.0 2025-09-24 09:20 UTC

This package is auto-updated.

Last update: 2025-10-13 00:20:01 UTC


README

Latest Version on Packagist Total Downloads

A comprehensive Laravel package for integrating with SteadFast Courier API. This package provides a clean, robust interface for managing orders, tracking shipments, and handling return requests with advanced features like bulk processing, caching, detailed logging, and event-driven architecture.

โœจ Features

  • โœ… Complete API Coverage: All SteadFast API endpoints implemented
  • ๐Ÿ“ฆ Individual & Bulk Orders: Efficient single and batch order processing
  • ๐Ÿ”„ Return Requests: Create and manage return requests
  • ๐Ÿ” Status Tracking: Real-time shipment status tracking
  • ๐Ÿ’ต Balance Management: Account balance verification
  • ๏ฟฝ Queue Support: Background processing for bulk operations
  • ๐Ÿ—‚๏ธ Comprehensive Validation: Input validation with custom rules
  • โš ๏ธ Advanced Error Handling: Specific exceptions for different error types
  • ๐Ÿง  Intelligent Caching: Optional response caching for better performance
  • ๐Ÿ“Š Detailed Logging: Request/response logging with statistics
  • ๐ŸŽญ Event System: Events for bulk operations monitoring
  • ๏ฟฝ๏ธ Artisan Commands: Built-in commands for testing and maintenance
  • ๐Ÿ” Retry Logic: Automatic retry with exponential backoff
  • ๐Ÿ”’ Data Security: Sensitive data filtering in logs

๐Ÿš€ Installation

Install the package via Composer:

composer require sabitahmad/laravel-steadfast

Install and configure the package:

php artisan steadfast:install

This will:

  • Publish the configuration file
  • Run the database migrations
  • Guide you through the setup process

โš™๏ธ Configuration

Add your SteadFast API credentials to your .env file:

# Required
STEADFAST_API_KEY=your_api_key_here
STEADFAST_SECRET_KEY=your_secret_key_here

# Optional - API Configuration
STEADFAST_BASE_URL=https://portal.packzy.com/api/v1
STEADFAST_TIMEOUT=30
STEADFAST_CONNECT_TIMEOUT=10

# Optional - Bulk Processing
STEADFAST_BULK_QUEUE=true
STEADFAST_BULK_CHUNK_SIZE=500
STEADFAST_QUEUE_NAME=default
STEADFAST_BULK_MAX_ATTEMPTS=3
STEADFAST_BULK_BACKOFF=60

# Optional - Retry Configuration
STEADFAST_RETRY_TIMES=3
STEADFAST_RETRY_SLEEP=1000

# Optional - Caching
STEADFAST_CACHE_ENABLED=false
STEADFAST_CACHE_TTL=300
STEADFAST_CACHE_PREFIX=steadfast

# Optional - Logging
STEADFAST_LOGGING=true
STEADFAST_LOG_REQUESTS=false
STEADFAST_LOG_RESPONSES=true
STEADFAST_CLEANUP_LOGS=true
STEADFAST_KEEP_LOGS_DAYS=30

# Optional - Validation
STEADFAST_STRICT_PHONE=true
STEADFAST_REQUIRE_EMAIL=false

Test your configuration:

php artisan steadfast:test

๐Ÿ“– Usage

Basic Order Creation

use SabitAhmad\SteadFast\SteadFast;
use SabitAhmad\SteadFast\DTO\OrderRequest;

$steadfast = new SteadFast();

// Basic order
$order = new OrderRequest(
    invoice: 'INV-2025-001',
    recipient_name: 'John Doe',
    recipient_phone: '01712345678',
    recipient_address: 'House 1, Road 2, Dhanmondi, Dhaka-1209',
    cod_amount: 1500.00,
    note: 'Handle with care'
);

$response = $steadfast->createOrder($order);
echo "Order created! Tracking: " . $response->getTrackingCode();

Advanced Order Creation

// Order with all optional fields
$order = new OrderRequest(
    invoice: 'INV-2025-001',
    recipient_name: 'John Doe',
    recipient_phone: '01712345678',
    recipient_address: 'House 1, Road 2, Dhanmondi, Dhaka-1209',
    cod_amount: 1500.00,
    alternative_phone: '01987654321',        // NEW: Alternative phone
    recipient_email: 'john@example.com',     // NEW: Email address
    note: 'Deliver between 10 AM - 2 PM',
    item_description: 'Electronics items',   // NEW: Item description
    total_lot: 2,                           // NEW: Total items
    delivery_type: 0                        // NEW: 0=home, 1=point delivery
);

$response = $steadfast->createOrder($order);

Using Facade

use SabitAhmad\SteadFast\Facades\SteadFast;

// Check balance
$balance = SteadFast::getBalance();
echo $balance->getFormattedBalance(); // "1,500.00 BDT"

// Create order
$response = SteadFast::createOrder($order);

Bulk Order Processing

// Create multiple orders
$orders = [
    new OrderRequest('INV-001', 'John Doe', '01712345678', 'Address 1', 1000),
    new OrderRequest('INV-002', 'Jane Smith', '01787654321', 'Address 2', 1500),
    OrderRequest::fromArray([
        'invoice' => 'INV-003',
        'recipient_name' => 'Bob Wilson',
        'recipient_phone' => '01611111111',
        'recipient_address' => 'Address 3',
        'cod_amount' => 2000,
        'delivery_type' => 1, // Point delivery
    ]),
];

// Process in background queue (recommended for large batches)
$response = $steadfast->bulkCreate($orders, true);
echo "Queued {$response->order_count} orders for processing";

// Process immediately (for small batches)
$response = $steadfast->bulkCreate($orders, false);
echo "Success rate: {$response->getSuccessRate()}%";
echo "Successful orders: {$response->success_count}";
echo "Failed orders: {$response->error_count}";

Order Status Tracking

// Multiple ways to track orders
$status = $steadfast->checkStatusByTrackingCode('ABC123XYZ');
$status = $steadfast->checkStatusByInvoice('INV-001');
$status = $steadfast->checkStatusByConsignmentId(12345);

// Rich status information
echo "Status: " . $status->delivery_status;
echo "Description: " . $status->getStatusDescription();

// Status checking methods
if ($status->isDelivered()) {
    echo "Order delivered successfully!";
} elseif ($status->isCancelled()) {
    echo "Order was cancelled";
} elseif ($status->isPending()) {
    echo "Order is still being processed";
} elseif ($status->isOnHold()) {
    echo "Order is on hold";
}

Return Requests (NEW Feature)

use SabitAhmad\SteadFast\DTO\ReturnRequest;

// Create return request by invoice
$returnRequest = ReturnRequest::byInvoice('INV-001', 'Customer requested return');
$response = $steadfast->createReturnRequest($returnRequest);

// Create return request by consignment ID
$returnRequest = ReturnRequest::byConsignmentId(12345, 'Damaged item');
$response = $steadfast->createReturnRequest($returnRequest);

// Create return request by tracking code
$returnRequest = ReturnRequest::byTrackingCode('ABC123', 'Wrong item delivered');
$response = $steadfast->createReturnRequest($returnRequest);

// Get single return request
$returnRequest = $steadfast->getReturnRequest(123);
echo "Status: " . $returnRequest->getStatusDescription();

// Check return status
if ($returnRequest->isPending()) {
    echo "Return request is pending approval";
} elseif ($returnRequest->isCompleted()) {
    echo "Return has been completed";
}

// Get all return requests
$returnRequests = $steadfast->getReturnRequests();
foreach ($returnRequests as $request) {
    echo "Return ID: {$request->id}, Status: {$request->status}";
}

Account Balance

$balance = $steadfast->getBalance();

echo "Current Balance: " . $balance->getFormattedBalance();
echo "Raw Amount: " . $balance->current_balance;

if ($balance->isSuccessful()) {
    echo "Balance retrieved successfully";
}

๐Ÿ”ง Advanced Features

Event System (NEW)

Listen to bulk order events for monitoring and notifications:

use SabitAhmad\SteadFast\Events\{BulkOrderStarted, BulkOrderCompleted, BulkOrderFailed};

// In your EventServiceProvider
Event::listen(BulkOrderStarted::class, function ($event) {
    Log::info("Bulk order processing started", [
        'order_count' => count($event->orders),
        'unique_id' => $event->uniqueId
    ]);
});

Event::listen(BulkOrderCompleted::class, function ($event) {
    // Send notification, update dashboard, etc.
    Log::info("Bulk order completed", [
        'success_count' => $event->response->success_count,
        'error_count' => $event->response->error_count,
        'success_rate' => $event->response->getSuccessRate()
    ]);
});

Event::listen(BulkOrderFailed::class, function ($event) {
    // Alert administrators, retry logic, etc.
    Log::error("Bulk order failed", [
        'error' => $event->exception->getMessage(),
        'order_count' => count($event->orders)
    ]);
});

Caching (NEW)

Enable intelligent caching for better performance:

// Enable caching in .env
STEADFAST_CACHE_ENABLED=true
STEADFAST_CACHE_TTL=300  // 5 minutes

// Clear cache when needed
$steadfast->clearCache(); // Clear all cache
$steadfast->clearCache('balance'); // Clear specific cache

Advanced Error Handling

use SabitAhmad\SteadFast\Exceptions\SteadfastException;

try {
    $response = $steadfast->createOrder($order);
} catch (SteadfastException $e) {
    match ($e->getCode()) {
        401 => $this->handleAuthenticationError($e), // Invalid credentials
        422 => $this->handleValidationError($e),     // Validation failed
        429 => $this->handleRateLimit($e),           // Rate limit exceeded
        503 => $this->handleServiceDown($e),         // Service unavailable
        default => $this->handleGenericError($e)
    };
}

private function handleValidationError(SteadfastException $e)
{
    $errors = $e->getContext()['validation_errors'] ?? [];
    foreach ($errors as $field => $messages) {
        echo "Field $field: " . implode(', ', $messages);
    }
}

private function handleRateLimit(SteadfastException $e)
{
    $retryAfter = $e->getContext()['retry_after'] ?? 60;
    echo "Rate limit exceeded. Retry after $retryAfter seconds";
}

Queue Configuration

For better queue management, configure dedicated queues:

// config/queue.php
'connections' => [
    'steadfast' => [
        'driver' => 'database',
        'table' => 'jobs',
        'queue' => 'steadfast-orders',
        'retry_after' => 300,
        'block_for' => 0,
    ],
],

// In your .env
STEADFAST_QUEUE_CONNECTION=steadfast
STEADFAST_QUEUE_NAME=high-priority

Run dedicated workers:

php artisan queue:work steadfast --queue=high-priority,default

๐Ÿ› ๏ธ Artisan Commands (NEW)

Test API Connection

# Test your configuration
php artisan steadfast:test

This command will:

  • Validate your API credentials
  • Test API connectivity
  • Check your current balance
  • Verify configuration settings

View Statistics

# View last 24 hours (default)
php artisan steadfast:stats

# View last 7 days
php artisan steadfast:stats --hours=168

# View last 30 days
php artisan steadfast:stats --hours=720

Sample output:

Steadfast API Statistics (Last 24 hours)
==================================================
Metric                | Value
---------------------|----------
Total Requests       | 1,245
Successful           | 1,180
Errors              | 65
Success Rate        | 94.78%
Bulk Operations     | 12
Average Duration    | 245.67ms

Top Endpoints:
Endpoint                    | Requests
---------------------------|----------
/create_order              | 890
/create_order/bulk-order   | 234
/status_by_invoice         | 121

Clean Up Old Logs

# Interactive cleanup
php artisan steadfast:cleanup

# Force cleanup without confirmation
php artisan steadfast:cleanup --force

๐Ÿ“Š Monitoring & Logging

Database Statistics

Query the logs table for insights:

use SabitAhmad\SteadFast\Models\SteadfastLog;

// Get recent errors
$errors = SteadfastLog::errors()->recent(24)->get();

// Get successful operations
$successful = SteadfastLog::successful()->recent(24)->get();

// Get bulk operations
$bulkOps = SteadfastLog::bulkOperations()->get();

// Get statistics
$stats = SteadfastLog::getStats(24); // Last 24 hours

Log Scopes

The SteadfastLog model includes useful query scopes:

// Filter by type
SteadfastLog::ofType('single_order')->get();

// Filter by status code
SteadfastLog::withStatusCode(200)->get();

// Get only errors
SteadfastLog::errors()->get();

// Get only successful requests
SteadfastLog::successful()->get();

// Get recent logs
SteadfastLog::recent(48)->get(); // Last 48 hours

// Get bulk operations
SteadfastLog::bulkOperations()->get();

๐Ÿ“‹ API Endpoints Coverage

Endpoint Method Description Status New Features
/create_order POST Create single order โœ… Enhanced validation, all fields
/create_order/bulk-order POST Create bulk orders โœ… Queue support, events, chunking
/status_by_cid/{id} GET Check status by consignment ID โœ… Rich status objects, caching
/status_by_invoice/{invoice} GET Check status by invoice โœ… Rich status objects, caching
/status_by_trackingcode/{code} GET Check status by tracking code โœ… Rich status objects, caching
/get_balance GET Get account balance โœ… Formatted output, caching
/create_return_request POST Create return request โœ… NEW - Full implementation
/get_return_request/{id} GET Get single return request โœ… NEW - Full implementation
/get_return_requests GET Get all return requests โœ… NEW - Full implementation

๐Ÿ” Validation Rules

The package includes comprehensive validation:

// Order validation rules
'invoice' => 'required|string|max:255|regex:/^[a-zA-Z0-9_-]+$/',
'recipient_name' => 'required|string|max:100',
'recipient_phone' => 'required|string|regex:/^01[0-9]{9}$/',
'alternative_phone' => 'nullable|string|regex:/^01[0-9]{9}$/',
'recipient_email' => 'nullable|email|max:255',
'recipient_address' => 'required|string|max:250',
'cod_amount' => 'required|numeric|min:0',
'note' => 'nullable|string|max:500',
'item_description' => 'nullable|string|max:500',
'total_lot' => 'nullable|integer|min:1',
'delivery_type' => 'nullable|integer|in:0,1',

Customize validation in config:

STEADFAST_STRICT_PHONE=true        # Enforce BD phone format
STEADFAST_REQUIRE_EMAIL=false      # Make email required
STEADFAST_MAX_INVOICE_LENGTH=255   # Max invoice length
STEADFAST_MAX_ADDRESS_LENGTH=250   # Max address length
STEADFAST_MAX_NAME_LENGTH=100      # Max name length

๐Ÿ”’ Security Features

Sensitive Data Protection

  • API keys automatically filtered from logs
  • Configurable request/response logging
  • Secure credential handling

Input Sanitization

  • Comprehensive input validation
  • SQL injection prevention
  • XSS protection in logged data

โšก Performance Optimizations

Bulk Processing

  • Chunked processing (configurable chunk size)
  • Queue-based background processing
  • Parallel processing support
  • Memory-efficient handling

Caching

  • Response caching for frequently accessed data
  • Configurable TTL per endpoint
  • Cache invalidation strategies
  • Redis/Database cache support

Connection Management

  • Persistent HTTP connections
  • Configurable timeouts
  • Retry logic with exponential backoff
  • Connection pooling

๐Ÿšจ Error Scenarios & Handling

Common Issues & Solutions

// Handle specific error scenarios
try {
    $response = $steadfast->createOrder($order);
} catch (SteadfastException $e) {
    if ($e->getCode() === 422) {
        // Validation errors
        $errors = $e->getContext()['validation_errors'];
        return response()->json(['errors' => $errors], 422);
    }
    
    if ($e->getCode() === 401) {
        // Invalid credentials - check API keys
        Log::error('Steadfast authentication failed', [
            'api_key' => substr(config('steadfast.api_key'), 0, 8) . '...'
        ]);
        return response()->json(['error' => 'API authentication failed'], 401);
    }
    
    if ($e->getCode() === 429) {
        // Rate limit - implement backoff strategy
        $retryAfter = $e->getContext()['retry_after'] ?? 60;
        return response()->json([
            'error' => 'Rate limit exceeded',
            'retry_after' => $retryAfter
        ], 429);
    }
}

๐Ÿ”„ Migration from v1.x

If upgrading from an older version:

  1. Update configuration:
php artisan vendor:publish --tag="laravel-steadfast-config" --force
  1. Run new migrations:
php artisan migrate
  1. Update your code:
// Old way
$steadfast->bulkCreate($orders);

// New way (same method, but now returns rich response objects)
$response = $steadfast->bulkCreate($orders);
echo $response->getSuccessRate(); // New methods available

๐Ÿงช Testing

Run the package tests:

composer test

Test your integration:

php artisan steadfast:test

๐Ÿ“ˆ Changelog

Please see CHANGELOG for more information on what has changed recently.

๐Ÿค Contributing

Please see CONTRIBUTING for details.

๐Ÿ” Security

Please review our security policy on how to report security vulnerabilities.

๐Ÿ‘ฅ Credits

๐Ÿ“„ License

The MIT License (MIT). Please see License File for more information.

๐Ÿ“ž Support

Getting Help

  1. Documentation: Read this README thoroughly
  2. Test Configuration: Run php artisan steadfast:test
  3. Check Logs: Query the steadfast_logs table for API issues
  4. View Statistics: Run php artisan steadfast:stats for insights
  5. GitHub Issues: Open an issue for bugs or feature requests

Troubleshooting

API Connection Issues:

# Test your configuration
php artisan steadfast:test

# Check recent errors
php artisan steadfast:stats --hours=1

Queue Processing Issues:

# Make sure queue worker is running
php artisan queue:work

# Check failed jobs
php artisan queue:failed

Common Configuration Issues:

  • Verify API credentials in .env
  • Ensure database migrations are run
  • Check queue configuration
  • Verify PHP version (8.1+ required)

Happy shipping with SteadFast! ๐Ÿ“ฆ๐Ÿš€