Skip to content

PHP

The read-only PHP SDK (FFI): install the package from Packagist and the native library from the release or source, open a vault, get a secret, handle typed exceptions, load a project.

6 min read

Requires PHP 8.2+ with the ffi extension. The default ffi.enable=preload allows FFI in CLI scripts and preloaded files; set ffi.enable=true for web SAPIs.

  1. Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
  2. Option 2: Set up with an AI coding agent. Run sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.

Two parts: the package, from Packagist, and the native library it loads, from the release (or built from source).

Terminal window
composer require sourceorrery/sourceorrery:0.3.1

sourceorrery/sourceorrery on Packagist (opens in a new tab) has every release as a version named by its tag. The package is the repository: Packagist reads composer.json at the repository root, so what Composer installs into vendor/sourceorrery/sourceorrery is the tree at that tag, with the SDK autoloaded from bindings/php/src/, and composer.lock records the exact commit (Supply chain). To try an unreleased revision, add https://github.com/Netizine/sourceorrery as a vcs repository and require dev-main.

The native library (libsourceorrery_ffi.so / .dylib / sourceorrery_ffi.dll) is in the sourceorrery-ffi-0.3.1-<target> archive on the v0.3.1 release (opens in a new tab). Download the one for your platform, unpack it, and name the directory in SOURCEORRERY_NATIVE_DIR:

Terminal window
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"
$dir = "$env:LOCALAPPDATA\sourceorrery-ffi"
Invoke-WebRequest "$release/sourceorrery-ffi-0.3.1-x86_64-pc-windows-msvc.zip" -OutFile sourceorrery-ffi.zip # aarch64-pc-windows-msvc on Arm
Expand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force
[Environment]::SetEnvironmentVariable("SOURCEORRERY_NATIVE_DIR", $dir, "User")

Verify a download against the release’s SHA256SUMS before unpacking it. Instead of the variable, the library can also sit under bindings/php/native/<os>-<arch>/ inside the installed package, or on the loader’s search path.

use SourceOrrery\SecretReader;
$reader = SecretReader::open('development');
$secret = $reader->get('database-password');
connect(password: $secret->value->expose());
$secret->close(); // zeroises the value
$reader->close();

With the default options, SOURCEORRERY_HOME locates the vault; this machine’s key in the OS credential store opens it, else the recovery key: an explicit one, SOURCEORRERY_RECOVERY_KEY, then a file or SOURCEORRERY_RECOVERY_KEY_FILE. SecretReader::open($vault, new OpenOptions(home: .., recoveryKey: .., recoveryKeyFile: .., environment: false)) overrides any of that. The SDK never prompts and never asks the vault’s view check.

A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.

Call Returns
$reader->get($name) Secret for the newest accessible version
$reader->get($name, $version) Secret for exactly that version
$reader->properties($name, $version = null) SecretProperties (policy not applied)
$reader->resolve('sourceorrery://development/database-password') Secret
$reader->descriptor() array describing the vault (no values)
$reader->close() releases the vault; the destructor does the same. A reader is the one owner of its native handle: clone and serialize() refuse, so share the object

$secret->properties (vault, name, version, enabled, contentType, tags, notBefore, expiresOn, createdOn, updatedOn as DateTimeImmutable, recoveryLevel, reference()) and $secret->value, a SecretValue:

$value->expose(); // string (a copy)
$value->length();
$value->close(); // zeroise; expose() throws LogicException afterwards
(string) $value; // "[REDACTED]"; json_encode and var_dump redact too; serialize() and clone refuse

Every failure is a SourceOrrery\SourceOrreryException or a subclass with code(), $detail, $hint and getMessage() (detail plus hint):

use SourceOrrery\{SecretReader, SecretNotFoundException, VaultLockedException, SourceOrreryException};
try {
$reader = SecretReader::open('development');
$secret = $reader->get('database-password');
} catch (VaultLockedException $e) {
error_log($e->hint); // which recovery-key sources were tried
} catch (SecretNotFoundException $e) {
error_log($e->hint); // "Store it with `sourceorrery secret set ...`"
} catch (SourceOrreryException $e) {
error_log("{$e->code()}: {$e->getMessage()}");
}

Classes: VaultNotFoundException, VaultLockedException, MigrationRequiredException, VaultMismatchException, SecretNotFoundException, VersionNotFoundException, SecretDeletedException, PolicyException with SecretDisabledException, SecretNotYetValidException (isTransient()), SecretExpiredException, IntegrityException, UnsupportedException, InvalidArgumentException, InvalidNameException, ManifestException, PermissionDeniedException, StorageException, UnauthenticatedException (the provider that stores the secret has no credentials for this process), ProviderUnavailableException (it could not be reached; isTransient()). See the SDK overview.

use SourceOrrery\Project;
$project = Project::load('sourceorrery.toml'); // or Project::load() to discover it
foreach ($project->secrets as $secret) {
putenv("{$secret->env}={$secret->value->expose()}");
}
$project->close();

Project::load resolves every [secrets.*] entry the way sourceorrery run does and throws the first required secret’s exception if one cannot be read.

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler (on Linux also pkg-config and libdbus-1-dev); Building from source has the commands for each platform. For this SDK, also PHP 8.2 or newer with the ffi extension (on Windows, enable extension=ffi in php.ini) and Composer.

The PHP code needs no build; what you build is the native library it loads:

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1 # or stay on main for the newest changes
cargo build --release -p sourceorrery-ffi
export SOURCEORRERY_NATIVE_DIR=/path/to/sourceorrery/target/release
# PowerShell: $env:SOURCEORRERY_NATIVE_DIR = "C:\path\to\sourceorrery\target\release"

With SOURCEORRERY_NATIVE_DIR naming target/release, the package from Packagist (or the vcs repository above) uses the library you built.

To run the tests, the example and the conformance harness, build the CLI too, which creates the test vault, and run the rest in Bash (Git Bash on Windows) from the repository root:

Terminal window
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIR
composer validate --strict composer.json # the manifest Packagist reads
php bindings/php/tests/run.php
php bindings/php/examples/get_secret.php "$SOURCEORRERY_TEST_VAULT" database-password
python tests/conformance/sdk/harness.py --runner php

The tests run from the command line, where PHP’s default ffi.enable=preload already allows FFI. What the fixture script creates: The SDK test vault. Source: bindings/php (opens in a new tab).