README

A PHP client library for the Boostr API.

Requirements

PHP 8.1+
Guzzle HTTP client

Installation

composer require foundryco/boostr

Basic Usage

use FoundryCo\Boostr\BoostrClient;

$client = new BoostrClient();

// Authenticate with email and password
$client->authenticate('user@example.com', 'password');

// Or set an existing token directly
$client->setToken('your-jwt-token');

// Fetch resources
$deals = $client->deals()->all();
$deal = $client->deals()->find(123);

Authentication

The Boostr API uses JWT token authentication. You can authenticate using your email and password:

$client = new BoostrClient();
$client->authenticate('user@example.com', 'password');

// Check if authenticated
if ($client->isAuthenticated()) {
    // Make API calls
}

Or if you already have a token:

$client->setToken('existing-jwt-token');

Querying Resources

Basic Queries

// Get all deals (returns first page)
$deals = $client->deals()->all();

// Get a single deal by ID
$deal = $client->deals()->find(123);

// Pass query parameters
$deals = $client->deals()->all(['page' => 2]);

Default Filter Behavior

By default, all queries include filter=all which returns all records accessible to your account. Without this filter, the API only returns records owned by the authenticated user.

// Default: returns all company records (filter=all)
$deals = $client->deals()->all();

// Override to get only your records
$deals = $client->deals()->all(['filter' => 'mine']);

Using QueryBuilder

The QueryBuilder provides a fluent interface for building queries:

use FoundryCo\Boostr\Support\QueryBuilder;

$query = QueryBuilder::make()
    ->page(2)
    ->createdAfter('2023-01-01')
    ->createdBefore('2023-12-31')
    ->updatedAfter('2023-06-01')
    ->filterMine();  // Override default filter=all

$deals = $client->deals()->all($query);

Available QueryBuilder Methods

page(int $page) - Set page number
filter(string $filter) - Set filter scope ('all', 'mine', etc.)
filterAll() - Shortcut for filter('all') (default behavior)
filterMine() - Shortcut for filter('mine') - only your records
createdAfter(string|DateTimeInterface $date) - Filter by created_at >= date
createdBefore(string|DateTimeInterface $date) - Filter by created_at <= date
updatedAfter(string|DateTimeInterface $date) - Filter by updated_at >= date
updatedBefore(string|DateTimeInterface $date) - Filter by updated_at <= date
where(string $key, mixed $value) - Add custom filter parameter

Pagination

The Boostr API uses fixed page sizes that vary by endpoint (typically 10-20 items per page). The API does not support custom page sizes.

Single Page

$response = $client->deals()->all();

// Get the data
$data = $response->getData();
$data = $response->toArray();

// Pagination info
$page = $response->getPage();
$hasNext = $response->hasNextPage();
$hasPrev = $response->hasPreviousPage();

// Convenience methods
$first = $response->first();
$last = $response->last();
$isEmpty = $response->isEmpty();
$count = count($response);

// Array access
$item = $response[0];

// Iteration
foreach ($response as $deal) {
    echo $deal['name'];
}

Fetching All Pages

To automatically paginate through all results:

// Returns a Generator that yields individual items
foreach ($client->deals()->paginate() as $deal) {
    echo $deal['name'];
}

// Or get all results as an array (may use significant memory for large datasets)
$allDeals = $client->deals()->allPages();

Available Resources

Standard Resources

These resources support all(), find(), paginate(), and allPages() methods:

$client->activities()->all();
$client->activities()->find($id);

$client->contacts()->all();
$client->contacts()->find($id);

$client->contracts()->all();
$client->contracts()->find($id);

$client->deals()->all();
$client->deals()->find($id);

$client->ios()->all();
$client->ios()->find($id);

$client->leads()->all();
$client->leads()->find($id);

$client->mediaPlans()->all();
$client->mediaPlans()->find($id);

$client->pmps()->all();
$client->pmps()->find($id);

$client->products()->all();
$client->products()->find($id);

$client->quotas()->all();
$client->quotas()->find($id);

$client->rateCards()->all();
$client->rateCards()->find($id);

$client->stages()->all();
$client->stages()->find($id);

$client->teams()->all();
$client->teams()->find($id);

$client->users()->all();
$client->users()->find($id);

List-Only Resources

These resources only support listing (no individual retrieval):

$client->activityTypes()->all();

Nested Resources

Some resources are accessed through parent resources:

// Content Fees for an IO
$client->contentFees()->forIo($ioId);
$client->contentFees()->findForIo($ioId, $contentFeeId);

// Deal Products for a Deal
$client->dealProducts()->forDeal($dealId);
$client->dealProducts()->findForDeal($dealId, $dealProductId);

// Display Line Items for an IO
$client->displayLineItems()->forIo($ioId);
$client->displayLineItems()->findForIo($ioId, $lineItemId);

// IO Line Items for an IO
$client->ioLineItems()->forIo($ioId);
$client->ioLineItems()->findForIo($ioId, $lineItemId);

// Itemized Costs for a Line Item
$client->itemizedCosts()->forLineItem($ioId, $lineItemId);
$client->itemizedCosts()->findForLineItem($ioId, $lineItemId, $costId);

// Media Plan Line Items
$client->mediaPlanLineItems()->forMediaPlan($mediaPlanId);
$client->mediaPlanLineItems()->findForMediaPlan($mediaPlanId, $lineItemId);

// PMP Items
$client->pmpItems()->forPmp($pmpId);
$client->pmpItems()->findForPmp($pmpId, $itemId);

// PMP Item Daily Actuals
$client->pmpItemDailyActuals()->forPmpItem($pmpId, $itemId);
$client->pmpItemDailyActuals()->findForPmpItem($pmpId, $itemId, $actualId);

Error Handling

The client throws specific exceptions for different error conditions:

use FoundryCo\Boostr\Exceptions\AuthenticationException;
use FoundryCo\Boostr\Exceptions\ApiException;
use FoundryCo\Boostr\Exceptions\BoostrException;

try {
    $client->authenticate('user@example.com', 'wrong-password');
} catch (AuthenticationException $e) {
    // Invalid credentials, expired token, etc.
}

try {
    $deal = $client->deals()->find(99999);
} catch (ApiException $e) {
    $statusCode = $e->getCode();       // HTTP status code
    $response = $e->getResponse();     // PSR-7 Response object
    $body = $e->getErrorBody();        // Parsed JSON error body
}

Custom Base URL

By default, the client connects to https://app.boostr.com. You can specify a different base URL:

$client = new BoostrClient('https://custom.boostr.com');

License

MIT

foundryco / boostr

Maintainers

Details