README

Official PHP SDK for the Bella Baxter secret management platform.

Requirements

PHP 8.1+
Extensions: ext-curl, ext-json, ext-openssl (all bundled by default)

Installation

composer require bella-baxter/sdk

Quick Start

use BellaBaxter\BaxterClient;
use BellaBaxter\BaxterClientOptions;

$client = new BaxterClient(new BaxterClientOptions(
    baxterUrl:       'https://baxter.example.com',
    clientId:        'bella_ak_abc123',       // from: bella apikeys create
    clientSecret:    'your-secret-here',
    environmentSlug: 'production',
    enableE2ee:      true,                    // end-to-end encryption
));

$secrets = $client->getAllSecrets();
echo $secrets['DATABASE_URL'];

End-to-End Encryption (E2EE)

When enableE2ee: true is set:

The SDK generates a P-256 ECDH key pair on startup
The public key is sent as X-E2E-Public-Key header with every request
The server encrypts the response using ECDH-P256 + HKDF-SHA256 + AES-256-GCM
The SDK decrypts the response transparently

Secret values are never visible in plaintext — not in server logs, proxies, or network captures.

// E2EE is opt-in — disabled by default
$clientWithE2ee = new BaxterClient(new BaxterClientOptions(
    // ...
    enableE2ee: true,
));

API

`getAllSecrets(): array<string,string>`

Fetches all secrets for the configured environment.

$secrets = $client->getAllSecrets();
// ['DATABASE_URL' => 'postgres://...', 'API_KEY' => '...']

`getSecret(string $key): string`

Fetches all secrets and returns a single value by key. Throws \RuntimeException if not found.

$dbUrl = $client->getSecret('DATABASE_URL');

`getSecretsVersion(int $version): array<string,string>`

Fetches secrets at a specific version snapshot.

$secrets = $client->getSecretsVersion(42);

Configuration

Option	Type	Default	Description
`baxterUrl`	`string`	—	Base URL of the Baxter API
`clientId`	`string`	—	API key client ID
`clientSecret`	`string`	—	API key client secret
`environmentSlug`	`string`	—	Environment slug (e.g. `production`)
`enableE2ee`	`bool`	`false`	Enable end-to-end encryption
`timeoutSeconds`	`int`	`10`	HTTP request timeout

Laravel Integration

// config/services.php
'bella' => [
    'url'         => env('BAXTER_URL'),
    'client_id'   => env('BAXTER_CLIENT_ID'),
    'client_secret' => env('BAXTER_CLIENT_SECRET'),
    'environment' => env('BAXTER_ENVIRONMENT', 'production'),
    'e2ee'        => env('BAXTER_E2EE', true),
],

// AppServiceProvider::register()
$this->app->singleton(BaxterClient::class, function () {
    return new BaxterClient(new BaxterClientOptions(
        baxterUrl:       config('services.bella.url'),
        clientId:        config('services.bella.client_id'),
        clientSecret:    config('services.bella.client_secret'),
        environmentSlug: config('services.bella.environment'),
        enableE2ee:      (bool) config('services.bella.e2ee'),
    ));
});

Symfony Integration

# config/services.yaml
BellaBaxter\BaxterClientOptions:
    arguments:
        $baxterUrl:       '%env(BAXTER_URL)%'
        $clientId:        '%env(BAXTER_CLIENT_ID)%'
        $clientSecret:    '%env(BAXTER_CLIENT_SECRET)%'
        $environmentSlug: '%env(BAXTER_ENVIRONMENT)%'
        $enableE2ee:      true

BellaBaxter\BaxterClient:
    arguments:
        $options: '@BellaBaxter\BaxterClientOptions'

Typed Secret Code Generation

bella secrets generate php fetches the secrets manifest (key names + type hints, no values) from the Bella API and generates a typed AppSecrets class. Each method calls getenv() at runtime — no secret values are ever embedded in the generated file.

bella secrets generate php \
  --project my-app \
  --environment production \
  --output AppSecrets.php

Generated AppSecrets.php:

<?php
// Auto-generated by bella secrets generate php — do not edit manually.

class AppSecrets
{
    public function getDatabaseUrl(): string
    {
        $v = getenv('DATABASE_URL');
        if ($v === false) throw new \RuntimeException("Secret 'DATABASE_URL' is not set.");
        return $v;
    }

    public function getPort(): int
    {
        $v = getenv('PORT');
        if ($v === false) throw new \RuntimeException("Secret 'PORT' is not set.");
        return (int) $v;
    }

    public function isEnableFeatureX(): bool
    {
        $v = getenv('ENABLE_FEATURE_X');
        if ($v === false) throw new \RuntimeException("Secret 'ENABLE_FEATURE_X' is not set.");
        return filter_var($v, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
    }
}

Usage alongside the SDK

// Secrets must be in the environment before accessing.
// Use bella run, the SDK (BaxterClient), or a .env file loaded at bootstrap.

$secrets = new AppSecrets();
$dbUrl = $secrets->getDatabaseUrl();  // string — throws if missing
$port  = $secrets->getPort();         // int — parsed automatically

Because each method reads getenv() on every call, values updated between requests (or via bella watch) are always current.

Options

Option	Default	Description
`-p, --project <slug>`	`.bella` context	Project slug
`-e, --environment <slug>`	`.bella` context	Environment slug
`--provider <slug>`	`default`	Provider slug
`-o, --output <path>`	`AppSecrets.php`	Output file path
`--class-name <name>`	`AppSecrets`	Class name
`--dry-run`	—	Print to stdout without writing

bella-baxter / sdk

Maintainers

Package info

Statistics

Security