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.
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.
Project setup options
Section titled “Project setup options”- 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.
- 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.
Install
Section titled “Install”Two parts: the package, from Packagist, and the native library it loads, from the release (or built from source).
The package, from Packagist
Section titled “The package, from Packagist”composer require sourceorrery/sourceorrery:0.3.1sourceorrery/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, from the release
Section titled “The native library, from the release”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:
$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 ArmExpand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force[Environment]::SetEnvironmentVariable("SOURCEORRERY_NATIVE_DIR", $dir, "User")release=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-aarch64-apple-darwin # x86_64-apple-darwin on Intelcurl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1export SOURCEORRERY_NATIVE_DIR=/opt/sourceorreryrelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-x86_64-unknown-linux-gnu # aarch64-unknown-linux-gnu on arm64curl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1export SOURCEORRERY_NATIVE_DIR=/opt/sourceorreryVerify 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.
Get a secret
Section titled “Get a secret”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 refuseErrors
Section titled “Errors”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.
Load a project
Section titled “Load a project”use SourceOrrery\Project;
$project = Project::load('sourceorrery.toml'); // or Project::load() to discover itforeach ($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.
Building from source
Section titled “Building from source”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:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffiexport 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:
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIRcomposer validate --strict composer.json # the manifest Packagist readsphp bindings/php/tests/run.phpphp bindings/php/examples/get_secret.php "$SOURCEORRERY_TEST_VAULT" database-passwordpython tests/conformance/sdk/harness.py --runner phpThe 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).