Supaship PHP SDK — feature flags in PHP

This guide documents server-side feature flag evaluation in PHP using the official SDK supashiphq/php-sdk (Packagist ).

Sources: Packagist supashiphq/php-sdk · GitHub SupashipHQ/php-sdk

What this integration does

Concept	Meaning
Feature flag	A named toggle or configuration (variation) you control from the Supaship dashboard without redeploying PHP code.
Fallback map	The `features` array: each key is a flag name; each value is the local default if Edge is unreachable or the flag is off.
Context	Attributes (e.g. `userId`, `email`, `plan`) sent with each evaluation so targeting rules and percentage rollouts apply.
Server SDK key	Credential for backend evaluation in PHP (do not use a browser-only client key on the server).

Use getFeature for one flag or getFeatures for several in a single HTTP request to Supaship Edge.

Requirements

PHP 7.4 or newer
PHP extensions: json, openssl (required for HTTPS to Edge)
A Server SDK Key for the target environment
A Supaship project with at least one feature flag defined

Installation

composer require supashiphq/php-sdk

Quick start

Minimal plain PHP example (no framework):


<?php
 
use Supaship\SupaClient;
 
$features = [
    'new-ui' => false,
    'theme-config' => [
        'primaryColor' => '#007bff',
        'darkMode' => false,
    ],
];
 
$client = new SupaClient([
    'sdkKey' => getenv('SUPASHIP_SDK_KEY'),
    'environment' => 'production',
    'features' => $features,
    'context' => [
        'userId' => '123',
        'email' => 'user@example.com',
        'plan' => 'premium',
    ],
]);
 
$isNewUi = $client->getFeature('new-ui');
$theme = $client->getFeature('theme-config');
 
$batch = $client->getFeatures(['new-ui', 'theme-config'], [
    'context' => ['userId' => '456'],
]);

Per-request context override

Pass extra context for a single call:


$client->getFeature('new-ui', ['context' => ['plan' => 'enterprise']]);

Configuration reference

Key	Required	Description
`sdkKey`	Yes	Supaship project Server SDK key.
`environment`	Yes	Environment slug (e.g. `production`, `staging`).
`features`	Yes	Fallback map: flag name → boolean, array, or `null`.
`context`	Yes	Default evaluation context (scalar values only).
`sensitiveContextProperties`	No	Property names whose values are SHA-256 hashed before the request (privacy; same idea as the JS SDK).
`networkConfig`	No	`featuresAPIUrl`, `eventsAPIUrl`, `requestTimeoutMs`, `retry`, optional `httpHandler` for tests or custom HTTP.

Evaluations are synchronous (each call waits for HTTP) unless you wrap calls (e.g. queue workers).

Public API (SupaClient)

getFeature(string $name, array $options = []): mixed — One flag; on transport failure returns the configured fallback (does not throw for typical network errors).
getFeatures(array $names, array $options = []): array — Batch evaluation; prefer this when loading many flags to reduce round-trips.
updateContext(array $context, bool $mergeWithExisting = true): void — Merge or replace default context (e.g. after login).
getContext(): ?array — Read the current default context.
getFeatureFallback(string $name): mixed — Read the configured fallback for a flag name.

Conceptual details (variation shapes, targeting, fallbacks) align with the JavaScript SDK API reference.

Framework guides (PHP)

Register one shared SupaClient per request lifecycle, call updateContext once the authenticated user is known, then use getFeature / getFeatures in controllers or services.

Laravel — config/supaship.php, AppServiceProvider singleton, Auth context, controller constructor injection
Symfony — services.yaml, %env()% parameters, KernelEvents::REQUEST subscriber, controller type-hint injection
CodeIgniter 4 — Config\Services, shared instance, filter for session/user context, controllers

Extended recipes (e.g. PHPUnit container swapping) live in the PHP SDK README — framework integrations .

Testing without network calls

For unit tests, avoid hitting Supaship Edge: set networkConfig.httpHandler or use Supaship\Testing\HttpStub.


use Supaship\SupaClient;
use Supaship\Testing\HttpStub;
 
$client = new SupaClient([
    'sdkKey' => 'test-key',
    'environment' => 'test',
    'features' => ['new-ui' => false],
    'context' => ['userId' => '42'],
    'networkConfig' => [
        'httpHandler' => HttpStub::success(['new-ui' => true]),
    ],
]);

See the PHP SDK — testing section for failure stubs and Laravel-specific examples.

Node.js server guide — Same flag model using @supashiphq/javascript-sdk
Packagist: supashiphq/php-sdk