vahidkaargar / bamboo-card-portal
This is Bamboocardportal.com package
Installs: 1 259
Dependents: 0
Suggesters: 0
Security: 0
Stars: 16
Watchers: 1
Forks: 0
Open Issues: 0
pkg:composer/vahidkaargar/bamboo-card-portal
Requires
- php: >=8.2
- guzzlehttp/guzzle: ^7.2|^8.0
- illuminate/cache: ^8.0|^9.0|^10.0|^11.0|^12.0
- illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0
- josantonius/http-status-code: ^1.0|^2.0
Requires (Dev)
- orchestra/testbench: ^8.10|^9.0|^10.0
- phpunit/phpunit: ^10|^11|^12
README
A professional Laravel package for seamless integration with the Bamboo Card Portal API. This package provides a robust, well-tested solution for interacting with Bamboo's services, featuring comprehensive exception handling, intelligent caching, Laravel facades, and extensive test coverage.
Table of Contents
- Features
- Requirements
- Installation
- Configuration
- Usage
- API Methods
- Testing
- Exception Types
- Cache Configuration
- Version 2 API
- Contributing
- License
- Changelog
- Support
Features
- Easy Integration: Simple API for interacting with Bamboo Card Portal
- Exception Handling: Comprehensive exception layer with specific exception types
- Intelligent Caching: Automatic caching for all API endpoints with smart cache keys
- Facade Support: Laravel facade for easy access
- Comprehensive Testing: Full test suite with unit and integration tests
- Configuration: Flexible configuration with environment variables
- Security: Built-in authentication and validation
- Performance: Optimized with intelligent caching to reduce API calls
- Laravel 12 Compatible: Full support for Laravel 5.x through 12.x
Requirements
- PHP >= 8.2
- Laravel 8.x, 9.x, 10.x, 11.x, or 12.x
Installation
Install the package via Composer:
composer require vahidkaargar/bamboo-card-portal
Configuration
Publish the configuration file:
php artisan vendor:publish --provider="vahidkaargar\BambooCardPortal\ServiceProviders\BambooServiceProvider" --tag="bamboo-config"
Environment Variables
Configure your environment variables in .env
:
# Sandbox Configuration BAMBOO_SANDBOX_MODE=false BAMBOO_SANDBOX_USERNAME=your_sandbox_username BAMBOO_SANDBOX_PASSWORD=your_sandbox_password # Production Configuration BAMBOO_PRODUCTION_USERNAME=your_production_username BAMBOO_PRODUCTION_PASSWORD=your_production_password # Cache Configuration BAMBOO_CACHE_ENABLED=false BAMBOO_CACHE_DRIVER=default BAMBOO_CACHE_PREFIX=bamboo BAMBOO_CACHE_TTL=3600 # Connection Configuration BAMBOO_CONNECTION_TIMEOUT=160
Usage
Using the Facade
use Bamboo; // All methods are available through the facade $orders = Bamboo::orders()->get(); $catalogs = Bamboo::catalogs()->get(); $accounts = Bamboo::accounts()->get();
Basic Usage
use vahidkaargar\BambooCardPortal\Bamboo; $bamboo = new Bamboo(); // Or Helper $bamboo = bamboo(); // Get orders $orders = $bamboo->orders() ->setStartDate('2023-01-01') ->setEndDate('2023-01-31') ->get(); // Create order $requestedId = Str::uuid(); $bamboo->orders() ->setRequestId($requestedId) ->setAccountId(123) ->setProducts([ ["ProductId" => $productId, "Quantity" => $quantity, "Value" => $value], ["ProductId" => $productId2, "Quantity" => $quantity2, "Value" => $value2], ["ProductId" => $productId3, "Quantity" => $quantity3, "Value" => $value3], ]) ->setProduct($productId4, $quantity4, $value4) ->checkout(); // Get specific order $order = $bamboo->orders()->get($requestedId);
Exception Handling
The package provides specific exceptions for different error scenarios:
use vahidkaargar\BambooCardPortal\Exceptions\{ AuthenticationException, ConfigurationException, NetworkException, ResourceNotFoundException, ValidationException }; try { $orders = $bamboo->orders()->get(); } catch (AuthenticationException $e) { // Handle authentication errors logger('Authentication failed: ' . $e->getMessage()); } catch (ResourceNotFoundException $e) { // Handle resource not found errors logger('Resource not found: ' . $e->getMessage()); } catch (ValidationException $e) { // Handle validation errors $errors = $e->getErrors(); logger('Validation errors: ' . json_encode($errors)); } catch (NetworkException $e) { // Handle network errors logger('Network error: ' . $e->getMessage()); }
Caching
The package includes intelligent caching functionality for all API endpoints:
// Cache is enabled by default for all endpoints $orders = $bamboo->orders()->get(); // This will be cached $catalogs = $bamboo->catalogs()->get(); // This will be cached $accounts = $bamboo->accounts()->get(); // This will be cached $transactions = $bamboo->transactions()->get(); // This will be cached $exchange = $bamboo->exchange()->rate(); // This will be cached // Disable caching in config // BAMBOO_CACHE_ENABLED=false // Use different cache driver // BAMBOO_CACHE_DRIVER=redis // Cache keys are automatically generated based on parameters $catalogs->setCurrencyCode('USD')->setCountryCode('US')->get(); // Unique cache key $transactions->setStartDate('2023-01-01')->setEndDate('2023-01-31')->get(); // Unique cache key
Configuration Options
// config/bamboo.php return [ 'sandbox_mode' => env('BAMBOO_SANDBOX_MODE', false), // Sandbox credentials 'sandbox_username' => env('BAMBOO_SANDBOX_USERNAME'), 'sandbox_password' => env('BAMBOO_SANDBOX_PASSWORD'), 'sandbox_base_url' => 'https://api-stage.bamboocardportal.com/api/integration/v1.0/', // Production credentials 'production_username' => env('BAMBOO_PRODUCTION_USERNAME'), 'production_password' => env('BAMBOO_PRODUCTION_PASSWORD'), 'production_base_url' => 'https://api.bamboocardportal.com/api/integration/v1.0/', 'production_v2_base_url' => 'https://api.bamboocardportal.com/api/integration/v2.0/', // Connection settings 'connection_timeout' => env('BAMBOO_CONNECTION_TIMEOUT', 160), // Cache settings 'cache' => [ 'enabled' => env('BAMBOO_CACHE_ENABLED', false), 'driver' => env('BAMBOO_CACHE_DRIVER', 'file'), 'prefix' => env('BAMBOO_CACHE_PREFIX', 'bamboo'), 'ttl' => env('BAMBOO_CACHE_TTL', 60), ], ];
API Methods
Orders
$orders = $bamboo->orders(); // Get orders with date range $orders->setStartDate('2023-01-01') ->setEndDate('2023-01-31') ->get(); // Create order $requestedId = Str::uuid(); $orders->setRequestId($requestedId) ->setAccountId(123) ->setProduct(1, 5, 100) ->checkout(); // Get specific order $orders->get($requestedId);
Catalogs
$catalogs = $bamboo->catalogs(); $products = $catalogs->get();
Accounts
$accounts = $bamboo->accounts(); $account = $accounts->get();
Exchange
$exchange = $bamboo->exchange(); $rates = $exchange->get();
Transactions
$transactions = $bamboo->transactions() ->setStartDate('2022-05-02') ->setEndDate('2022-05-20') ->get();
Notifications
$notifications = $bamboo->notifications(); $notification = $notifications->get();
Testing
Run the test suite:
composer test
The package includes comprehensive tests for:
- Unit tests for all components
- Integration tests for API interactions
- Exception handling tests
- Cache functionality tests
- Facade tests
Exception Types
BambooException
: Base exception classAuthenticationException
: Authentication failures (401)ConfigurationException
: Configuration errorsNetworkException
: Network/connection errorsResourceNotFoundException
: Resource not found (404)ValidationException
: Validation errors (422)
Cache Configuration
The package supports various cache drivers and includes intelligent caching for all API endpoints:
Supported Cache Drivers
array
: Default in-memory cacheredis
: Redis cachedatabase
: Database cachefile
: File-based cache
Cached Endpoints
All API endpoints are automatically cached with intelligent cache keys:
Exchange Rates
$exchange = $bamboo->exchange() ->setBaseCurrency('USD') ->setCurrency('EUR') ->rate(); // Cache key: exchange_rate_USD_EUR
Catalogs
$catalogs = $bamboo->catalogs() ->setVersion(2) ->setCurrencyCode('USD') ->setCountryCode('US') ->setPageSize(50) ->get(); // Cache key: catalog_2_{payload_hash}
Accounts
$accounts = $bamboo->accounts()->get(); // Cache key: accounts
Transactions
$transactions = $bamboo->transactions() ->setStartDate('2023-01-01') ->setEndDate('2023-01-31') ->get(); // Cache key: transactions_2023-01-01_2023-01-31
Orders
$orders = $bamboo->orders() ->setStartDate('2023-01-01') ->setEndDate('2023-01-31') ->get(); // Cache key: orders_2023-01-01_2023-01-31
Cache Benefits
- Performance: Reduces API calls for frequently accessed data
- Cost Savings: Fewer API requests to Bamboo Card Portal
- Speed: Faster response times for cached data
- Configurable: Can be enabled/disabled and TTL adjusted via config
- Smart Keys: Automatic cache key generation based on parameters
Contributing
We welcome contributions to improve this package. Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Write tests for your changes
- Ensure all tests pass (
composer test
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
This package is open-sourced software licensed under the MIT license.
Changelog
Version 1.0.0
- Initial release with basic API integration
- Support for orders, catalogs, accounts, exchange, transactions, and notifications
- Basic configuration management
- Added Laravel 12 compatibility
- Implemented comprehensive exception handling system
- Added intelligent caching with configurable drivers for all API endpoints
- Introduced Laravel facade for improved developer experience
- Enhanced test coverage with unit and integration tests
- Improved error handling and validation
- Added support for multiple cache drivers (Redis, Database, File, Array)
- Automatic caching for Exchange, Catalogs, Accounts, and Transactions
- Smart cache key generation based on method parameters
- Configurable cache TTL and driver selection
Support
For support and questions:
- Open an issue on GitHub
- Contact the maintainer at vahidkaargar@gmail.com
- Check the documentation for detailed examples