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

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

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

  • 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: