Brazebee PHP SDK

Official PHP SDK for tracking customer journey events with Brazebee.

Installation


composer require brazebee/sdk

Requirements

PHP 8.1 or higher
Guzzle HTTP client

Quick Start


<?php
 
require_once 'vendor/autoload.php';
 
use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\TrackEventRequest;
use Brazebee\Events\Types\CompanyInfo;
use Brazebee\Events\Types\UserInfo;
 
// Initialize the client
$client = new BrazebeeClient(
    'your_api_key_here',
    ['baseUrl' => 'https://your-app.com']
);
 
// Track an event
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'acme_corp',
        'name' => 'Acme Corporation',
        'paymentProvider' => 'stripe',
        'paymentProviderId' => 'cus_abc123',
        'crmProvider' => 'salesforce',
        'crmProviderId' => 'acct_456'
    ]),
    'user' => new UserInfo([
        'id' => 'user_123',
        'email' => 'john@acme.com',
        'name' => 'John Doe'
    ]),
    'eventKey' => 'feature_used',
    'data' => [
        'feature' => 'export',
        'format' => 'csv'
    ]
]);
 
$client->events->track($request);

Usage

Track User Events

Track events with user context:


use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo, UserInfo};
 
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'acme_corp',
        'name' => 'Acme Corporation'
    ]),
    'user' => new UserInfo([
        'id' => 'user_123',
        'email' => 'john@acme.com',
        'name' => 'John Doe'
    ]),
    'eventKey' => 'onboarding_completed',
    'data' => [
        'steps_completed' => 5,
        'time_taken_seconds' => 180
    ]
]);
 
$client->events->track($request);

Track Company-Level Events (Without User)

Track company-level events without a specific user (system events):


use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo};
 
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'acme_corp',
        'name' => 'Acme Corporation'
    ]),
    // No user parameter - this is a company/system event
    'eventKey' => 'plan_upgraded',
    'data' => [
        'from_plan' => 'starter',
        'to_plan' => 'professional',
        'mrr_change' => 50
    ]
]);
 
$client->events->track($request);

Custom Data Fields

Add custom fields to the data parameter:


use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo, UserInfo};
 
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'acme_corp',
        'name' => 'Acme Corporation'
    ]),
    'user' => new UserInfo([
        'id' => 'user_123',
        'email' => 'john@acme.com',
        'name' => 'John Doe'
    ]),
    'eventKey' => 'feature_used',
    'data' => [
        // Standard fields
        'feature' => 'export',
        'format' => 'csv',
        
        // Custom fields (any data you want to track)
        'company_plan' => 'enterprise',
        'user_role' => 'admin',
        'records_exported' => 1500,
        'processing_time_ms' => 250
    ]
]);
 
$client->events->track($request);

Multi-Tenant Usage

Track events for multiple companies with a single API key:


use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo, UserInfo};
 
// Your organization uses one API key for all client companies
$client = new BrazebeeClient(
    'your_api_key_here',
    ['baseUrl' => 'https://your-app.com']
);
 
// Track event for Company A
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'company_a',
        'name' => 'Company A Inc'
    ]),
    'user' => new UserInfo(['id' => 'user_from_company_a']),
    'eventKey' => 'feature_used',
    'data' => ['feature' => 'export']
]);
$client->events->track($request);
 
// Track event for Company B
$request = new TrackEventRequest([
    'company' => new CompanyInfo([
        'id' => 'company_b',
        'name' => 'Company B Corp'
    ]),
    'user' => new UserInfo(['id' => 'user_from_company_b']),
    'eventKey' => 'feature_used',
    'data' => ['feature' => 'import']
]);
$client->events->track($request);

Configuration


$client = new BrazebeeClient(
    'your_api_key_here',                      // Required: Your Brazebee API key (string)
    [
        'baseUrl' => 'https://your-app.com',  // Required: Your API base URL
        'timeout' => 60                       // Optional: Request timeout in seconds (default: 60)
    ]
);

Configuration Options

Option	Type	Required	Description
`apiKey`	`string`	✅ Yes	Your Brazebee API key (first parameter)
`baseUrl`	`string`	✅ Yes	Your Brazebee API base URL
`timeout`	`int`	❌ No	Request timeout in seconds (default: 60)

Store your API key in environment variables using getenv('BRAZEBEE_API_KEY') for security.

Error Handling


use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo};
use Brazebee\Exceptions\BrazebeeApiException;
 
$client = new BrazebeeClient(
    'your_api_key_here',
    ['baseUrl' => 'https://your-app.com']
);
 
try {
    $request = new TrackEventRequest([
        'company' => new CompanyInfo([
            'id' => 'acme_corp',
            'name' => 'Acme Corporation'
        ]),
        'eventKey' => 'feature_used'
    ]);
    
    $client->events->track($request);
    
} catch (BrazebeeApiException $e) {
    echo "API Error: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->getCode() . "\n";        // Use getCode(), not getStatusCode()
    echo "Response: " . json_encode($e->getBody()) . "\n";
}

Common Error Codes

Status Code	Description
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid API key
404	Not Found - Event key not configured
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Type Reference

Required Types


use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\TrackEventRequest;
use Brazebee\Events\Types\CompanyInfo;
use Brazebee\Events\Types\UserInfo;
use Brazebee\Exceptions\BrazebeeApiException;

CompanyInfo

Required fields:

id (string) - Unique identifier for the company
name (string) - Company name

Optional fields:

paymentProvider (string) - Payment provider (e.g., stripe, paddle, chargebee, custom)
paymentProviderId (string) - Customer ID in the payment provider system
crmProvider (string) - CRM platform name (e.g., salesforce, hubspot)
crmProviderId (string) - Account/Company ID in the CRM


$company = new CompanyInfo([
    'id' => 'acme_corp',          // Required
    'name' => 'Acme Corporation', // Required
    'paymentProvider' => 'stripe', // Optional
    'paymentProviderId' => 'cus_abc123', // Optional
    'crmProvider' => 'salesforce', // Optional
    'crmProviderId' => 'acct_456' // Optional
]);

UserInfo

Required fields:

id (string) - Unique identifier for the user

Optional fields:

email (string) - User email address
name (string) - User full name


$user = new UserInfo([
    'id' => 'user_123',           // Required
    'email' => 'john@acme.com',   // Optional
    'name' => 'John Doe'          // Optional
]);

TrackEventRequest

Required fields:

company (CompanyInfo) - Company information
eventKey (string) - Event key to track

Optional fields:

user (UserInfo) - User information (optional for company/system events)
data (array) - Custom event data
timestamp (DateTime) - Event timestamp (defaults to current time)


$request = new TrackEventRequest([
    'company' => $company,         // Required
    'eventKey' => 'feature_used',  // Required
    'user' => $user,               // Optional
    'data' => [...],               // Optional
    'timestamp' => new DateTime()  // Optional
]);

Framework Integration

Laravel

Create a service for Brazebee tracking:


// app/Services/BrazebeeService.php
<?php
 
namespace App\Services;
 
use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo, UserInfo};
 
class BrazebeeService
{
    private BrazebeeClient $client;
 
    public function __construct()
    {
        $this->client = new BrazebeeClient(
            config('services.brazebee.api_key'),
            ['baseUrl' => config('services.brazebee.base_url')]
        );
    }
 
    public function trackEvent(
        string $companyId,
        string $companyName,
        string $eventKey,
        array $data = [],
        ?string $userId = null,
        ?string $userEmail = null,
        ?string $userName = null
    ): void {
        $request = new TrackEventRequest([
            'company' => new CompanyInfo([
                'id' => $companyId,
                'name' => $companyName
            ]),
            'eventKey' => $eventKey,
            'data' => $data
        ]);
 
        if ($userId) {
            $request = new TrackEventRequest([
                'company' => new CompanyInfo([
                    'id' => $companyId,
                    'name' => $companyName
                ]),
                'user' => new UserInfo([
                    'id' => $userId,
                    'email' => $userEmail,
                    'name' => $userName
                ]),
                'eventKey' => $eventKey,
                'data' => $data
            ]);
        }
 
        $this->client->events->track($request);
    }
}

Add to config/services.php:


'brazebee' => [
    'api_key' => env('BRAZEBEE_API_KEY'),
    'base_url' => env('BRAZEBEE_BASE_URL'),
],

Use in your controllers:


use App\Services\BrazebeeService;
 
class FeatureController extends Controller
{
    public function __construct(
        private BrazebeeService $brazebee
    ) {}
 
    public function export(Request $request)
    {
        // Your export logic...
 
        $this->brazebee->trackEvent(
            companyId: auth()->user()->company_id,
            companyName: auth()->user()->company->name,
            eventKey: 'feature_used',
            data: [
                'feature' => 'export',
                'format' => $request->format
            ],
            userId: auth()->id(),
            userEmail: auth()->user()->email,
            userName: auth()->user()->name
        );
 
        return response()->json(['success' => true]);
    }
}

Symfony

Create a service in your services configuration:


# config/services.yaml
services:
    Brazebee\BrazebeeClient:
        arguments:
            $apiKey: '%env(BRAZEBEE_API_KEY)%'
            $options:
                baseUrl: '%env(BRAZEBEE_BASE_URL)%'

Use in your controllers:


use Brazebee\BrazebeeClient;
use Brazebee\Events\Types\{TrackEventRequest, CompanyInfo, UserInfo};
 
class FeatureController extends AbstractController
{
    public function __construct(
        private BrazebeeClient $brazebee
    ) {}
 
    public function export(Request $request): JsonResponse
    {
        // Your export logic...
 
        $this->brazebee->events->track(new TrackEventRequest([
            'company' => new CompanyInfo([
                'id' => $this->getUser()->getCompanyId(),
                'name' => $this->getUser()->getCompanyName()
            ]),
            'user' => new UserInfo([
                'id' => $this->getUser()->getId(),
                'email' => $this->getUser()->getEmail(),
                'name' => $this->getUser()->getName()
            ]),
            'eventKey' => 'feature_used',
            'data' => ['feature' => 'export']
        ]));
 
        return $this->json(['success' => true]);
    }
}

Environment Variables

Best practice for storing configuration:


# .env file
BRAZEBEE_API_KEY=your_api_key_here
BRAZEBEE_BASE_URL=https://your-app.com


<?php
 
$client = new BrazebeeClient(
    getenv('BRAZEBEE_API_KEY'),
    ['baseUrl' => getenv('BRAZEBEE_BASE_URL')]
);

Support

Documentation: https://brazebee.com/docs
Email: dev@brazebee.com
GitHub: https://github.com/brazebee/brazebee-sdk-php

License

Apache-2.0