README

Laravel package for pushing billing events and usage records to the Rabosh billing platform.

Installation

composer require rabosh/laravel

Configuration

Publish the config file:

php artisan vendor:publish --tag=rabosh-config

Add to your .env:

RABOSH_API_KEY=your-api-key
RABOSH_API_SECRET=your-api-secret

Optionally override the API URL (defaults to https://api.rabosh.com):

RABOSH_BASE_URL=https://custom-instance.example.com

Usage

Push a billing event

use Rabosh\Facades\Rabosh;

// Simple event
Rabosh::event('api.request', [
    'endpoint' => '/users',
    'method' => 'GET',
]);

// With timestamp
Rabosh::event('sms.sent', [
    'recipient' => '+1234567890',
    'segments' => 2,
], now()->toIso8601String());

Async (queued) events

Enable in .env:

RABOSH_QUEUE_ENABLED=true
RABOSH_QUEUE_CONNECTION=redis
RABOSH_QUEUE_NAME=billing

Rabosh::eventAsync('api.request', ['endpoint' => '/users']);

Push usage records

use Rabosh\Facades\Rabosh;

// Single usage record
Rabosh::usageRecord('api-calls', 1.0);

// With timestamp and metadata
Rabosh::usageRecord('storage-gb', 2.5, now()->toIso8601String(), [
    'bucket' => 'uploads',
]);

// Async (queued)
Rabosh::usageRecordAsync('api-calls', 1.0);

// Batch — send multiple records in one request
Rabosh::usageRecordBatch([
    ['metered_feature_id' => 'api-calls', 'amount' => 5],
    ['metered_feature_id' => 'storage-gb', 'amount' => 1.2, 'metadata' => ['bucket' => 'media']],
]);

Dependency injection

use Rabosh\RaboshClient;

class MyService
{
    public function __construct(private RaboshClient $rabosh) {}

    public function doWork(): void
    {
        $this->rabosh->event('work.completed', ['duration_ms' => 150]);
        $this->rabosh->usageRecord('jobs-processed', 1.0);
    }
}

Buffer & Retry (Offline Resilience)

When the Rabosh API is unreachable, the SDK can buffer failed requests locally so no billing data is lost. Buffered requests are stored as JSON files and retried later.

Enable the buffer

In .env:

RABOSH_BUFFER_ENABLED=true
RABOSH_BUFFER_PATH=   # optional, defaults to storage/rabosh/buffer

Retry buffered requests

Run manually:

php artisan rabosh:retry-buffered

Or schedule it in your app/Console/Kernel.php:

$schedule->command('rabosh:retry-buffered')->everyFiveMinutes();

Check buffer status

$pending = Rabosh::bufferCount();

Error Handling

By default, the package will never throw exceptions into your application. All failures (network errors, auth errors, server errors) are caught internally and logged via Laravel's Log facade with a [Rabosh] prefix. Your application continues to run normally.

// This is safe — if the Rabosh API is down, the call logs the error,
// buffers the request (if enabled), and returns [].
Rabosh::event('api.request', ['endpoint' => '/users']);

Queued events (eventAsync, usageRecordAsync) also handle failures gracefully. The jobs retry 3 times and log the failure if all retries are exhausted — they will never surface an unhandled exception in your application.

Checking for failures

Since event() and usageRecord() return an empty array on failure, you can detect issues:

$result = Rabosh::event('api.request', ['endpoint' => '/users']);

if (empty($result)) {
    // The event was not delivered — check your logs for details.
    // If buffer is enabled, it's stored for retry.
}

rabosh / laravel

Maintainers

Package info

Statistics

Security