vahidkaargar/bamboo-card-portal

This is Bamboocardportal.com package

v1.0.0 2025-10-05 14:00 UTC

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

MIT

• Vahid Kaargar

• api
• laravel
• bamboo
• bamboocardportal

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
  • Environment Variables
• Usage
  • Using the Facade
  • Basic Usage
  • Exception Handling
  • Caching
  • Configuration Options
• API Methods
  • Orders
  • Catalogs
  • Accounts
  • Exchange
  • Transactions
  • Notifications
• Testing
• Exception Types
• Cache Configuration
• Version 2 API
• Contributing
• License
• Changelog
  • Version 1.0.0
• 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 class
• AuthenticationException: Authentication failures (401)
• ConfigurationException: Configuration errors
• NetworkException: Network/connection errors
• ResourceNotFoundException: 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 cache
• redis: Redis cache
• database: Database cache
• file: 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:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (composer test)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. 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 [e-mail]
• Check the documentation for detailed examples