Using LaunchDarkly feature flags and Experimentation with WordPress

Published May 21, 2026

by Glynn Jordan

This tutorial explains how to integrate LaunchDarkly with a self-hosted WordPress site for feature flagging and experimentation. It covers the available SDK approaches, how to handle WordPress-specific constraints like caching, and how to structure your implementation depending on whether your goal is controlled feature rollouts or A/B testing.

WordPress powers a large share of the web, and many organizations use it alongside modern JavaScript front ends and microservice architectures. LaunchDarkly supports this kind of mixed environment through a combination of the PHP server-side SDK and the JavaScript client-side SDK.

Prerequisites

To complete this tutorial, you should have:

• A self-hosted WordPress installation with PHP 8.1 or higher
• Composer available in your WordPress environment
• A LaunchDarkly account with at least one project and environment configured
• Access to your WordPress theme files or a custom plugin

Concepts

Before you read this tutorial, you should understand the following:

• Feature flags are the foundation of LaunchDarkly. A feature flag controls whether a code path, UI element, or experience is active for a given user or group of users. Flags can be boolean (on/off) or multivariate (returning strings, numbers, or JSON). Everything in LaunchDarkly, including experiments, is built on top of flags.
• Experimentation uses flags to run A/B and multivariate tests. An experiment assigns users to variants through a flag’s targeting rules, then measures the effect on defined metrics. Experimentation requires flag evaluation to be consistent per user and per session. The same user must always see the same variant for the duration of the test.
• Server-side SDKs evaluate flags on the server before the page is rendered and sent to the browser. This eliminates client-side performance concerns like cold start delays and flicker.
• Client-side SDKs evaluate flags in the browser after the page loads. They are simpler to set up but require additional care to avoid flicker in experimentation scenarios.
• Bootstrapping is a technique where a server-side SDK pre-evaluates all flags for a given user and injects the results into the HTML response. The client-side SDK then initializes instantly using those values, with no additional network request.
• Contexts are the objects LaunchDarkly uses to evaluate flags and record experiment data. A context has a kind (usually user) and a key that uniquely identifies the entity being evaluated.

Choose your approach

There are two main approaches to integrating LaunchDarkly with WordPress. Your choice depends on your WordPress setup and requirements.

Most production experimentation use cases on self-hosted WordPress will benefit from the PHP SDK approach. The sections below cover both approaches.

Option 1: PHP SDK with bootstrapping (recommended)

This approach evaluates flags server-side in PHP and injects the results into the page before it reaches the browser. The JavaScript SDK initializes instantly from those pre-evaluated values.

Step 1: Install the PHP SDK

From your WordPress root or theme directory, install the SDK using Composer:

$
composer require launchdarkly/server-sdk

Then include the autoloader in your theme’s functions.php:

1
require_once __DIR__ . '/vendor/autoload.php';

The LaunchDarkly PHP SDK version 6.x requires PHP 8.1 or higher. Starting with version 6.6, it also requires the apcu PHP extension to be installed and enabled.

Step 2: Evaluate flags in PHP and inject bootstrap data

Add the following to your theme’s functions.php. This function evaluates all client-side flags for the current user and outputs them as an inline script that the JavaScript SDK can read on initialization.

1
use LaunchDarkly\LDClient;
2
use LaunchDarkly\LDContext;
3
4
function ld_get_visitor_id() {
5
    if ( ! isset( $_COOKIE['ld_visitor_id'] ) ) {
6
        $visitor_id = bin2hex( random_bytes( 16 ) );
7
        setcookie( 'ld_visitor_id', $visitor_id, [
8
            'expires'  => time() + YEAR_IN_SECONDS,
9
            'path'     => '/',
10
            'secure'   => is_ssl(),
11
            'httponly' => false, // JS SDK needs to read this
12
            'samesite' => 'Lax',
13
        ] );
14
        $_COOKIE['ld_visitor_id'] = $visitor_id; // available to other code on this request
15
    }
16
    return sanitize_text_field( $_COOKIE['ld_visitor_id'] );
17
}
18
19
function ld_get_bootstrap_data( $visitor_id ) {
20
    $context_key = is_user_logged_in() ? (string) get_current_user_id() : $visitor_id;
21
22
    $context = LDContext::builder( $context_key )
23
        ->set( 'loggedIn', is_user_logged_in() )
24
        ->build();
25
26
    // Initialize the PHP SDK
27
    // For high-traffic sites, configure the PHP SDK to use the Relay Proxy instead
28
    $client = new LDClient( 'YOUR_SDK_KEY' );
29
30
    // allFlagsState() returns data in the exact format the JS SDK expects for bootstrap
31
    return $client->allFlagsState( $context, [ 'clientSideOnly' => true ] );
32
}
33
34
function ld_inject_bootstrap_script() {
35
    $visitor_id  = ld_get_visitor_id();
36
    $flag_state  = ld_get_bootstrap_data( $visitor_id );
37
    echo '<script>'
38
        . 'var ldVisitorId = ' . wp_json_encode( $visitor_id ) . ';'
39
        . 'var ldBootstrap = ' . wp_json_encode( $flag_state ) . ';'
40
        . '</script>';
41
}
42
add_action( 'wp_head', 'ld_inject_bootstrap_script', 1 );

Step 3: Initialize the JavaScript SDK with bootstrap data

In your theme or page template, initialize the JavaScript SDK using the injected bootstrap values. The SDK will be immediately ready with no network fetch required.

Register the SDK script alongside your other theme assets. We recommend self-hosting the SDK file rather than loading it from a third-party CDN like unpkg or jsDelivr, which we do not support for production use. To learn more, read the JavaScript SDK reference.

1
function ld_enqueue_js_sdk() {
2
    wp_enqueue_script(
3
        'launchdarkly-js-client-sdk',
4
        get_template_directory_uri() . '/js/launchdarkly-js-client-sdk.min.js',
5
        [],
6
        'EXAMPLE-VERSION', // pin to an exact SDK version
7
        false // load in the <head>
8
    );
9
}
10
add_action( 'wp_enqueue_scripts', 'ld_enqueue_js_sdk' );

Handling caching

Full-page caching (WP Rocket, W3 Total Cache, Nginx FastCGI, Cloudflare, and similar caching layers) stores a rendered HTML snapshot and serves it to all subsequent visitors. This means PHP does not re-execute per user, and the same evaluated flag values are served to everyone.

This is not a LaunchDarkly-specific limitation. It affects any server-side A/B testing tool running on a cached WordPress page.

There are two approaches to resolve this.

Approach A: Hybrid cookie pattern (recommended)

This pattern keeps full-page caching enabled for the majority of traffic while ensuring each user receives a correctly bucketed, consistent variant.

How it works:

1. New visitors (with no variant cookie) bypass the cache and hit PHP, which evaluates the flag and sets a per-user cookie
2. The caching layer is configured to serve cached pages only when the variant cookie is present
3. On subsequent visits, the cached page loads and the JavaScript SDK reads the variant from the cookie with no PHP execution, no network call, no flicker

If you’re using PHP, evaluate once and set a cookie:

1
use LaunchDarkly\LDClient;
2
use LaunchDarkly\LDContext;
3
4
function ld_set_variant_cookie() {
5
    $flag_key    = 'your-experiment-flag';
6
    $cookie_name = 'ld_variant_' . $flag_key;
7
8
    // If the user already has a variant assignment, do nothing
9
    if ( isset( $_COOKIE[ $cookie_name ] ) ) {
10
        return;
11
    }
12
13
    $visitor_id  = ld_get_visitor_id(); // shared helper from Step 2
14
    $context_key = is_user_logged_in() ? (string) get_current_user_id() : $visitor_id;
15
    $context     = LDContext::builder( $context_key )->build();
16
    $client      = new LDClient( 'YOUR_SDK_KEY' );
17
    $variant     = $client->variation( $flag_key, $context, 'control' );
18
19
    // Write the variant to a cookie readable by the JS SDK on cached loads
20
    setcookie( $cookie_name, $variant, [
21
        'expires'  => time() + ( 30 * DAY_IN_SECONDS ),
22
        'path'     => '/',
23
        'domain'   => '.yourdomain.com', // replace with your domain
24
        'secure'   => is_ssl(),
25
        'httponly' => false, // JS SDK needs to read this
26
        'samesite' => 'Lax',
27
    ] );
28
}
29
add_action( 'template_redirect', 'ld_set_variant_cookie' );

Set the variant cookie expiration to match or exceed your typical experiment duration. If a returning visitor’s variant cookie has expired, they’ll be re-bucketed on their next visit, which can cause variant jumping in long-running experiments.

If you’re using JavaScript, read the variant on cached page loads:

1
function getCookieValue(name) {
2
  const match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
3
  return match ? match[2] : null;
4
}
5
6
const context = {
7
  kind: 'user',
8
  key: getCookieValue('ld_visitor_id')
9
};
10
11
const variant = getCookieValue('ld_variant_your-experiment-flag') ?? 'control';
12
13
const ldClient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', context, {
14
  bootstrap: { 'your-experiment-flag': variant }
15
});

Cache bypass configuration

Configure your caching layer to bypass cache when the variant cookie is absent, for example, new visitors who need a fresh PHP evaluation:

Approach B: Exclude experiment pages from caching

It is also possible to disable caching entirely on pages where an experiment is running. This is the simplest configuration change but means those pages lose the performance benefit of full-page caching.

We generally do not recommend this approach for SEO-critical or high-traffic landing pages where cache performance is a requirement. It may be appropriate for lower-traffic pages where cache performance is less important.

Option 2: JavaScript SDK only (client-side)

If you are unable to modify PHP or are running on a platform where PHP execution is restricted, you can use the JavaScript SDK alone.

Self-host the SDK file alongside your other JavaScript resources and load it from your theme’s <head> using wp_enqueue_script().

1
<!-- Load the self-hosted SDK file via wp_enqueue_script() in functions.php -->
2
<script>
3
  let visitorId = localStorage.getItem('ld_visitor_id');
4
  if (!visitorId) {
5
    visitorId = crypto.randomUUID();
6
    localStorage.setItem('ld_visitor_id', visitorId);
7
  }
8
9
  const ldClient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', {
10
    kind: 'user',
11
    key: visitorId,
12
    anonymous: true
13
  }, {
14
    bootstrap: 'localStorage'
15
  });
16
17
  ldClient.on('ready', () => {
18
    const variant = ldClient.variation('your-flag-key', 'control');
19
    // apply variant
20
  });
21
</script>

Mitigating flicker in client-side mode

When the SDK loads asynchronously, the page renders before flag values are available. Users may briefly see the control variant before the treatment is applied. This is called “flicker.”

To prevent flicker, hide the element under test until the SDK is ready, then reveal it:

1
// CSS
2
.ld-pending {
3
  visibility: hidden;
4
}
5
// JavaScript
6
ldClient.on('ready', () => {
7
  const variant = ldClient.variation('your-flag-key', 'control');
8
  // apply variant logic
9
  document.querySelectorAll('.ld-pending').forEach(el => {
10
    el.style.visibility = 'visible';
11
  });
12
});

Loading the SDK with async or defer improves page load metrics but makes flicker worse, because the page renders before the script executes. If you use async/defer, the CSS hide pattern above becomes essential. The PHP bootstrap approach in Option 1 eliminates this tradeoff entirely.

By default, the JavaScript SDK fetches flags from LaunchDarkly on every page load, so the ~100–200ms cold start applies to every initialization. To cache flag values across visits, pass bootstrap: 'localStorage' to LDClient.initialize(). With this enabled, after the first visit the SDK reads cached values from localStorage and emits the ready event immediately, while still fetching the latest values in the background. Note that this can introduce stale-value flicker if flags change between visits, and that first-time visitors still see the full cold start. The PHP bootstrap approach in Option 1 avoids both tradeoffs.

Feature flags in WordPress

Feature flags let you control which users see which experiences without code deployments. Common use cases in WordPress include:

• Gradual rollouts: Roll out a new page template, content block, or UI component to a percentage of visitors before releasing to everyone
• Targeted experiences: Serve specific content to users based on attributes like country, logged-in status, or subscription tier
• Kill switches: Instantly disable a feature if problems arise, without a deployment
• Beta access: Expose new features only to specific users or groups

Example: show a new hero section to 20% of visitors

In your WordPress template, add the following:

1
$visitor_id = ld_get_visitor_id();
2
$context = LDContext::builder( $visitor_id )->build();
3
$client  = new LDClient( 'YOUR_SDK_KEY' );
4
5
if ( $client->variation( 'new-hero-section', $context, false ) ) {
6
    get_template_part( 'template-parts/hero', 'new' );
7
} else {
8
    get_template_part( 'template-parts/hero', 'default' );
9
}

In the LaunchDarkly UI, set the flag to a 20% percentage rollout to gradually expose the new hero to traffic. Increase the percentage as confidence grows, or roll back instantly by turning the flag off.

Experimentation in WordPress

Experimentation builds on feature flags to run controlled A/B tests and measure the effect of changes on defined metrics. The typical WordPress experimentation flow involves the landing page (WordPress), downstream conversion pages (often React or other front-end apps), and a metric like signup or purchase completion.

Setting up a simple experiment

To set up an experiment:

1. Create a multivariate flag: In the LaunchDarkly UI, create a string flag with two variations, for example, control and treatment. Enable client-side SDK access on the flag.
2. Create a metric: Create a custom event metric in LaunchDarkly. For example, a metric named “signup-completed” tied to an event key of signup-completed. Set the metric type to Occurrence (did this event happen for this user at all?).
3. Create the experiment: Create an experiment, attach the flag, select the metric, and configure the traffic allocation. Set the targeting rule to evaluate the flag for all users or a specific segment, then start the experiment.
4. Evaluate the flag on the WordPress landing page (LP):

1
$variant = $client->variation( 'lp-hero-experiment', $context, 'control' );
2
3
if ( $variant === 'treatment' ) {
4
    // render treatment version
5
} else {
6
    // render control version
7
}

5. Track the conversion event from your downstream app: When the user completes the goal action (for example, signup), fire a track() call from wherever that event occurs, whether that’s the WordPress page itself or a downstream React application:

1
ldClient.track('signup-completed');

LaunchDarkly connects the track() event to the experiment exposure using the same context key. As long as the same userId or visitorId is used consistently across your WordPress LP and downstream apps, attribution will be correct.

Passing variant decisions to downstream apps

If your WordPress LP is the entry point but conversion happens in a React app on the same domain, you can persist the variant assignment in a cookie and read it in the downstream app without re-initializing LaunchDarkly:

1
// In WordPress PHP — write the variant to a cross-subdomain cookie
2
setcookie( 'lp_variant', $variant, time() + ( 24 * 60 * 60 ), '/', '.yourdomain.com' );

This approach requires the WordPress LP and the React app to share the same root domain. If they are on separate domains, initialize the LaunchDarkly SDK in each app using the same context key instead.

Anonymous visitor to authenticated user

When a user arrives anonymously and later signs up or logs in, you can link their pre-login experiment exposure to their authenticated identity using a multi-context identify call. This ensures experiment attribution is preserved across the anonymous and authenticated states.

At the moment of login or signup:

1
ldClient.identify({
2
  kind: 'multi',
3
  user: {
4
    key: authenticatedUserId, // your system's user ID
5
    loggedIn: true
6
  },
7
  visitor: {
8
    key: visitorId, // the anonymous ID used before login
9
    anonymous: true // see note below
10
  }
11
});

Using the Relay Proxy in daemon mode

For WordPress sites with significant traffic, configure the PHP SDK to use the LaunchDarkly Relay Proxy in daemon mode. The Relay Proxy maintains a persistent connection to LaunchDarkly and stores flag data in Redis or DynamoDB. This means:

• The PHP SDK reads flag values from a local store on every request, with no outbound HTTP call to LaunchDarkly
• Flag updates are received by the Relay Proxy and propagated to the store in real time
• Your WordPress server is isolated from any LaunchDarkly availability events

1
// Daemon mode: SDK reads flag data directly from a persistent store
2
// that the Relay Proxy keeps up to date. No per-request HTTP call to LaunchDarkly.
3
4
use LaunchDarkly\Integrations\Redis;
5
6
$client = new LaunchDarkly\LDClient( 'YOUR_SDK_KEY', [
7
    'feature_requester' => Redis::featureRequester( [
8
        'redis_host' => 'localhost',
9
        'redis_port' => 6379,
10
    ] ),
11
] );

This requires the launchdarkly/server-sdk-redis-predis (or launchdarkly/server-sdk-redis-phpredis) Composer package, and the Relay Proxy must be configured to write to the same Redis instance. To learn more, read Using daemon mode and Storing data.

To learn more, read The Relay Proxy.

Conclusion

In this tutorial, you learned how to:

• Install and configure the LaunchDarkly PHP SDK in a self-hosted WordPress environment
• Bootstrap the JavaScript SDK with server-evaluated flag values to eliminate cold start delays and flicker
• Handle full-page caching using a hybrid cookie pattern that preserves cache performance
• Use feature flags for controlled rollouts and targeted content in WordPress templates
• Set up A/B experiments across a WordPress LP and downstream React applications
• Link anonymous visitor identities to authenticated user identities using multi-context

For more information, read:

• PHP SDK reference
• JavaScript SDK reference
• Bootstrapping
• Experimentation
• Contexts
• Relay Proxy