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:

1. The SDK generates a P-256 ECDH key pair on startup
2. The public key is sent as X-E2E-Public-Key header with every request
3. The server encrypts the response using ECDH-P256 + HKDF-SHA256 + AES-256-GCM
4. 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

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