PHP SDK
Feature flags and "In your code" experiments on your server, decided the same way the browser decides them, and events sent from it. It's one file for PHP 8.1 or newer, with no dependencies: plain PHP, Laravel, Symfony, WordPress and WooCommerce.
Install
curl -o Peekbird.php https://peekbird.com/sdk/Peekbird.phpThen make the client, with a key from Site settings → Server keys:
require_once __DIR__ . '/Peekbird.php';
// The key is in Site settings → Server keys.
$peekbird = new \Peekbird\Peekbird(getenv('PEEKBIRD_KEY'));It needs ext-curl or allow_url_fopen to reach Peekbird. PHP's requests don't share memory, so the SDK keeps your flags and experiments in a file in the temporary folder for 30 seconds, and most requests never ask Peekbird at all. Until the first download, flags are off and experiments answer null.
Decide
// visitor() and variation() set Peekbird's cookies: call them before any output.
$visitor = $peekbird->visitor();
if ($peekbird->variation('one-page-checkout', $visitor) === 'one-page') {
// Show the new version.
}$visitor = $peekbird->visitor();
if ($peekbird->flag('new-search', $visitor)) {
// The new feature.
}variation()answers the variation's key, ornullwhen the visitor isn't in the test. It counts them in the test the first time: ask where the variations start to differ.flag()answerstrueorfalse. Flags set no cookies, so they can be asked anywhere. Each answer is noted once per visitor, for the Feature flag filter.- Cookies are headers, so
visitor()andvariation()must come before any output. If output has started, the decision still works, the cookie is skipped, andonErrorsays where the output started.
Send events
$peekbird->track($visitor, 'purchase', ['revenue' => 49.9, 'currency' => 'USD', 'orderId' => 'ORDER-123']);revenue, value, currency and orderId are Peekbird's own fields; anything else that's text, a number or true/false goes along as a property. $peekbird->identify($visitor, ['id' => …, 'email' => …, 'name' => …]) says who the visitor is.
Events go at the end of the request. On PHP-FPM and LiteSpeed they're sent after the response has gone out, so the visitor doesn't wait. If Peekbird can't be reached then, they're lost, since nothing outlives a PHP request.
The visitor
$peekbird->visitor() reads the current request: Peekbird's cookies, User-Agent, Accept-Language, Referer, the page's address, Sec-GPC, and behind Cloudflare CF-IPCountry and CF-Region-Code. Call it once per request and pass the visitor around.
// Facts you know, added to what the request says:
$visitor = $peekbird->visitor(['attributes' => ['plan' => 'pro', 'ltv' => 250], 'timeZone' => 'Europe/Berlin']);
// Or a visitor you describe, with your own ID: nothing is read from the request, no cookie is set.
$visitor = $peekbird->visitor(['id' => 'user-42', 'attributes' => ['plan' => 'pro'], 'country' => 'DE']);The facts you can give: id, attributes, url, userAgent, language, country, region, city, regionCode, referrer, cookies, timeZone, qa, consent and gpc. What else a server knows, and what it can't, is on Server-side SDKs.
Plain PHP
<?php
require_once __DIR__ . '/Peekbird.php';
$peekbird = new \Peekbird\Peekbird(getenv('PEEKBIRD_KEY'));
// Before any output.
$visitor = $peekbird->visitor();
$checkout = $peekbird->variation('one-page-checkout', $visitor);
?>
<!doctype html>
<html>
<body>
<?php if ($checkout === 'one-page'): ?>
<?php include 'checkout-one-page.php'; ?>
<?php else: ?>
<?php include 'checkout-steps.php'; ?>
<?php endif; ?>
</body>
</html>Laravel
// app/Providers/AppServiceProvider.php, with Peekbird.php in composer.json's "autoload": {"files": [...]}
public function register(): void
{
$this->app->singleton(Peekbird::class, fn () => new Peekbird(config('services.peekbird.key'), [
// The middleware below puts the cookies on Laravel's response.
'setCookies' => false,
]));
}A middleware makes the visitor and puts its cookies on Laravel's response:
class PeekbirdVisitor
{
public function __construct(private Peekbird $peekbird)
{
}
public function handle(Request $request, Closure $next): Response
{
$visitor = $this->peekbird->visitor(
['attributes' => ['plan' => $request->user()?->plan]],
$request->server->all(),
);
$request->attributes->set('peekbird', $visitor);
$response = $next($request);
// After the controller: its decisions may have added _peekbird_exp.
foreach ($visitor->cookiesToSet() as $cookie) {
$response->headers->set('Set-Cookie', $cookie['header'], false);
}
return $response;
}
public function terminate(Request $request, Response $response): void
{
$this->peekbird->flush();
}
}// bootstrap/app.php (Laravel 11+): the snippet reads Peekbird's cookies as they are.
->withMiddleware(function (Middleware $middleware) {
$middleware->encryptCookies(except: ['_peekbird_uid', '_peekbird_exp']);
$middleware->web(append: [\App\Http\Middleware\PeekbirdVisitor::class]);
})In Laravel 10, add the two cookie names to $except in EncryptCookies, and the middleware to the web group. In a controller:
public function checkout(Request $request, Peekbird $peekbird)
{
$visitor = $request->attributes->get('peekbird');
return view($peekbird->variation('one-page-checkout', $visitor) === 'one-page' ? 'checkout.one-page' : 'checkout.steps');
}Symfony is the same idea: a listener on kernel.request makes the visitor, one on kernel.response adds the cookies. With Octane, RoadRunner or Swoole, pass the request's server variables as visitor()'s second argument and call flush() after each request.
WordPress and WooCommerce
<?php
/*
* Plugin Name: Peekbird
* wp-content/mu-plugins/peekbird.php, with Peekbird.php in wp-content/mu-plugins/peekbird/
* and define('PEEKBIRD_KEY', 'sk_…'); in wp-config.php.
*/
require_once __DIR__ . '/peekbird/Peekbird.php';
function peekbird(): \Peekbird\Peekbird
{
static $client = null;
return $client ??= new \Peekbird\Peekbird(PEEKBIRD_KEY);
}
function peekbird_visitor(): \Peekbird\Visitor
{
static $visitor = null;
return $visitor ??= peekbird()->visitor();
}
// WordPress hasn't sent anything yet here: the place to decide experiments.
add_action('template_redirect', function () {
$GLOBALS['peekbird_checkout'] = peekbird()->variation('one-page-checkout', peekbird_visitor());
});
// A WooCommerce purchase.
add_action('woocommerce_thankyou', function ($order_id) {
$order = wc_get_order($order_id);
if (!$order) {
return;
}
peekbird()->track(peekbird_visitor(), 'purchase', [
'revenue' => (float) $order->get_total(),
'currency' => $order->get_currency(),
'orderId' => (string) $order->get_order_number(),
]);
});In a theme template, use what was decided:
<?php if (($GLOBALS['peekbird_checkout'] ?? null) === 'one-page') : ?>
…
<?php endif; ?>
<?php // Flags set no cookies: ask them anywhere, even in a template. ?>
<?php if (peekbird()->flag('new-search', peekbird_visitor())) : ?>
…
<?php endif; ?>template_redirect runs once WordPress knows which page it is, and before anything is sent; wp_head is too late for cookies. A page cache (WP Super Cache, W3 Total Cache, LiteSpeed Cache, Cloudflare APO, Varnish) sends everyone the same page without running PHP: don't cache pages that change per visitor, or make the change in the page with the snippet instead.
Consent
Where your site waits for consent (see Consent), the SDK follows the same rule as the snippet. For a visitor who hasn't agreed, it sets no cookies and sends no events, and experiments answer null. Flags are still answered, since deciding one stores and sends nothing. Tell it what your own banner knows with ['consent' => true].
Options
$peekbird = new \Peekbird\Peekbird(getenv('PEEKBIRD_KEY'), [
'refreshSeconds' => 30, // how long the cached flags and experiments are used before asking again
'timeoutSeconds' => 2, // the longest each request to Peekbird may take
'onError' => fn (string $message, ?Throwable $error) => error_log($message), // never thrown
'cacheDir' => sys_get_temp_dir(), // where the flags and experiments are cached
'setCookies' => true, // false: set $visitor->cookiesToSet() on your response yourself
]);Nothing the SDK does throws into your code: it tells onError, once per kind of problem, and answers as if there were no flags or experiments.
