PHPackages                             vahidkaargar/bamboo-card-portal - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. vahidkaargar/bamboo-card-portal

ActiveLibrary[API Development](/categories/api)

vahidkaargar/bamboo-card-portal
===============================

This is Bamboocardportal.com package

v1.0.0(7mo ago)162.0k1MITPHPPHP >=8.2CI passing

Since Sep 3Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/vahidkaargar/bamboo-card-portal)[ Packagist](https://packagist.org/packages/vahidkaargar/bamboo-card-portal)[ RSS](/packages/vahidkaargar-bamboo-card-portal/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (7)Versions (25)Used By (0)

Bamboo Card Portal Laravel Package
==================================

[](#bamboo-card-portal-laravel-package)

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

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Environment Variables](#environment-variables)
- [Usage](#usage)
    - [Using the Facade](#using-the-facade)
    - [Basic Usage](#basic-usage)
    - [Exception Handling](#exception-handling)
    - [Caching](#caching)
    - [Configuration Options](#configuration-options)
- [API Methods](#api-methods)
    - [Orders](#orders)
    - [Catalogs](#catalogs)
    - [Accounts](#accounts)
    - [Exchange](#exchange)
    - [Transactions](#transactions)
    - [Notifications](#notifications)
- [Testing](#testing)
- [Exception Types](#exception-types)
- [Cache Configuration](#cache-configuration)
- [Version 2 API](#version-2-api)
- [Contributing](#contributing)
- [License](#license)
- [Changelog](#changelog)
    - [Version 1.0.0](#version-100)
- [Support](#support)

Features
--------

[](#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
------------

[](#requirements)

- PHP >= 8.2
- Laravel 8.x, 9.x, 10.x, 11.x, or 12.x

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require vahidkaargar/bamboo-card-portal
```

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --provider="vahidkaargar\BambooCardPortal\ServiceProviders\BambooServiceProvider" --tag="bamboo-config"
```

### Environment Variables

[](#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
-----

[](#usage)

### Using the Facade

[](#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

[](#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

[](#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

[](#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

[](#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
-----------

[](#api-methods)

### Orders

[](#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)

```
$catalogs = $bamboo->catalogs();
$products = $catalogs->get();
```

### Accounts

[](#accounts)

```
$accounts = $bamboo->accounts();
$account = $accounts->get();
```

### Exchange

[](#exchange)

```
$exchange = $bamboo->exchange();
$rates = $exchange->get();
```

### Transactions

[](#transactions)

```
$transactions = $bamboo->transactions()
      ->setStartDate('2022-05-02')
      ->setEndDate('2022-05-20')
      ->get();
```

### Notifications

[](#notifications)

```
$notifications = $bamboo->notifications();
$notification = $notifications->get();
```

Testing
-------

[](#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
---------------

[](#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
-------------------

[](#cache-configuration)

The package supports various cache drivers and includes intelligent caching for all API endpoints:

### Supported Cache Drivers

[](#supported-cache-drivers)

- `array`: Default in-memory cache
- `redis`: Redis cache
- `database`: Database cache
- `file`: File-based cache

### Cached Endpoints

[](#cached-endpoints)

All API endpoints are automatically cached with intelligent cache keys:

#### **Exchange Rates**

[](#exchange-rates)

```
$exchange = $bamboo->exchange()
    ->setBaseCurrency('USD')
    ->setCurrency('EUR')
    ->rate(); // Cache key: exchange_rate_USD_EUR
```

#### **Catalogs**

[](#catalogs-1)

```
$catalogs = $bamboo->catalogs()
    ->setVersion(2)
    ->setCurrencyCode('USD')
    ->setCountryCode('US')
    ->setPageSize(50)
    ->get(); // Cache key: catalog_2_{payload_hash}
```

#### **Accounts**

[](#accounts-1)

```
$accounts = $bamboo->accounts()->get(); // Cache key: accounts
```

#### **Transactions**

[](#transactions-1)

```
$transactions = $bamboo->transactions()
    ->setStartDate('2023-01-01')
    ->setEndDate('2023-01-31')
    ->get(); // Cache key: transactions_2023-01-01_2023-01-31
```

#### **Orders**

[](#orders-1)

```
$orders = $bamboo->orders()
    ->setStartDate('2023-01-01')
    ->setEndDate('2023-01-31')
    ->get(); // Cache key: orders_2023-01-01_2023-01-31
```

### Cache Benefits

[](#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
------------

[](#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
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

Changelog
---------

[](#changelog)

### Version 1.0.0

[](#version-100)

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

[](#support)

For support and questions:

- Open an issue on [GitHub](https://github.com/vahidkaargar/bamboo-card-portal/issues)
- Contact the maintainer at
- Check the [documentation](https://github.com/vahidkaargar/bamboo-card-portal) for detailed examples

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance64

Regular maintenance activity

Popularity28

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~33 days

Recently: every ~66 days

Total

24

Last Release

219d ago

Major Versions

v0.9.6.6 → v1.0.0-beta.1.02025-10-05

PHP version history (2 changes)v0.1PHP >=7.4

v1.0.0-beta.1.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/7b5c1e29f86cb6c6ff19aeb5691fe3f16f5d391871eb4ac4250e6bf8ddc6a4d1?d=identicon)[vahidkaargar](/maintainers/vahidkaargar)

---

Top Contributors

[![vahidkaargar](https://avatars.githubusercontent.com/u/3912242?v=4)](https://github.com/vahidkaargar "vahidkaargar (117 commits)")

---

Tags

apibamboocreditcardgiftcardsmobogiftapilaravelbamboobamboocardportal

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/vahidkaargar-bamboo-card-portal/health.svg)

```
[![Health](https://phpackages.com/badges/vahidkaargar-bamboo-card-portal/health.svg)](https://phpackages.com/packages/vahidkaargar-bamboo-card-portal)
```

###  Alternatives

[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[vluzrmos/slack-api

Wrapper for Slack.com WEB API.

102589.1k3](/packages/vluzrmos-slack-api)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[dragon-code/laravel-json-response

Automatically always return a response in JSON format

1118.6k1](/packages/dragon-code-laravel-json-response)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)