Download the PHP package nayemuf/pathao-courier without Composer

Laravel Pathao Courier Package

A professional Laravel package for integrating with Pathao Courier Merchant API. This package provides a clean, well-structured interface for all Pathao API endpoints with built-in caching, rate limiting, and comprehensive error handling.

✨ Features

• ✅ Complete API Coverage - All 11 Pathao Merchant API endpoints implemented
• ✅ OAuth 2.0 Authentication - Automatic token management with intelligent caching
• ✅ Rate Limiting - Built-in protection against API abuse (configurable)
• ✅ Input Validation - Comprehensive validation before API calls
• ✅ Error Handling - Detailed exception messages with field-level errors
• ✅ Laravel Best Practices - Service Provider, Facades, and publishable config
• ✅ Sandbox & Production - Full support for both environments
• ✅ Type Safety - Complete type hints and PHPDoc documentation
• ✅ Zero Configuration - Works out of the box with sensible defaults

📋 Requirements

• PHP >= 8.2
• Laravel >= 10.0
• Guzzle HTTP Client >= 7.0

📦 Installation

Install the package via Composer:

The package will automatically register its service provider and facade.

⚙️ Configuration

Step 1: Publish Configuration

Publish the configuration file to your config directory:

This will create config/pathao.php in your Laravel application.

Step 2: Environment Variables

Add the following to your .env file:

🧪 Sandbox Credentials (for Testing)

Pathao provides sandbox credentials for testing:

📍 Test Store IDs (Sandbox)

You can use any of these store IDs for testing in the sandbox environment:

Note: To get the full list of available stores, use:

🚀 Usage

Create an Order

Create Bulk Orders

Get Order Information

Get Cities, Zones, and Areas

Calculate Delivery Price

Store Management

Refresh Access Token

📚 API Reference

Authentication

• PathaoCourier::refreshToken(string $refreshToken) - Refresh access token using refresh token

Order API

• PathaoCourier::order()->create(array $orderData) - Create a new order
• PathaoCourier::order()->createBulk(array $orders) - Create multiple orders at once
• PathaoCourier::order()->getInfo(string $consignmentId) - Get order short info
• PathaoCourier::order()->getDetails(string $consignmentId) - Get full order details

Area API

• PathaoCourier::area()->getCities() - Get list of all cities
• PathaoCourier::area()->getZones(int $cityId) - Get zones for a specific city
• PathaoCourier::area()->getAreas(int $zoneId) - Get areas for a specific zone

Store API

• PathaoCourier::store()->create(array $storeData) - Create a new store
• PathaoCourier::store()->list() - Get list of all stores
• PathaoCourier::store()->getInfo(int $storeId) - Get merchant store info

Price API

• PathaoCourier::price()->calculate(array $priceData) - Calculate delivery price

⚠️ Error Handling

The package throws Nayemuf\PathaoCourier\Exceptions\PathaoException for all API errors:

🔒 Caching

Access tokens are automatically cached using Laravel's cache system to reduce API calls. Tokens are cached for their full lifetime (5 days) minus 5 minutes for safety. The cache key is configurable in config/pathao.php.

🚦 Rate Limiting

The package includes built-in rate limiting to prevent API abuse. By default, it limits requests to 60 per minute. You can configure this in your config/pathao.php:

✅ Validation Rules

All input data is validated before sending to the API:

• Recipient name: 3-100 characters
• Recipient phone: Exactly 11 characters (must start with 01)
• Recipient address: 10-220 characters
• Item weight: 0.5-10 kg
• Delivery type: 48 (Normal) or 12 (On Demand)
• Item type: 1 (Document) or 2 (Parcel)
• Item quantity: Minimum 1

🧪 Testing

Run the test suite:

Or run PHPUnit directly:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

Before contributing, please ensure you follow these guidelines:

1. Follow PSR-4 Autoloading Standard - All code must adhere to PSR-4 autoloading standards
2. Refer to Pathao Official Documentation First - Always check the Pathao API Documentation before implementing new features or changes
3. Maintain Code Quality - Follow existing code style, add proper type hints, and include PHPDoc comments
4. Write Tests - Include tests for new features or bug fixes
5. Update Documentation - Update README, CHANGELOG, and inline documentation as needed

Contribution Process

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the guidelines above
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request with a clear description of your changes

📝 Changelog

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

🔗 Links

• Packagist
• GitHub Repository
• Pathao API Documentation

📄 License

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

👤 Author

Nayem Uddin

• Email: [email protected]
• GitHub: @nayemuf
• LinkedIn: @nayemuf

🙏 Acknowledgments

• Pathao for providing the Merchant API
• Laravel community for the amazing framework

🐛 Reporting Issues

For issues, questions, or feature requests, please open an issue on GitHub.

💝 Support

If this package helps you, please consider giving it a ⭐ on Packagist or GitHub.