Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/avilavi44/wp-server-side-ab/archive/refs/heads/main.zipA small WordPress plugin for server-side A/B testing. PHP picks the variant before the page is sent, so there is no flicker and no JavaScript dependency.
The problem
Client-side A/B tools swap content after the page loads, which causes flicker and hurts page speed. Doing it on the server fixes that, but creates a new problem: WordPress sites usually sit behind a page cache, and a cache will happily serve one visitor's variant to everyone. This plugin handles the assignment and takes care of the cache side.
How it works
- Sticky, deterministic bucketing. A visitor gets one random id in a cookie (
ssab_id). The variant is a hash of the experiment key and that id, so nothing is stored per experiment, and a visitor's bucket in one test is independent of their bucket in another. - Cache safety. See Page caches below.
- Signed preview links. An HMAC token forces a variant for whoever opens the link, until it expires. It works for reviewers with no account on the site, and it sets no cookie and reports no exposure.
- Exposure reporting. An action fires once per experiment per request, for your analytics to hook.
The bucketing and signing live in plain PHP classes (includes/class-ssab-bucketer.php and includes/class-ssab-preview-token.php) that call no WordPress functions.
Install
Copy this folder into wp-content/plugins/ and activate it. There is no build step. Needs WordPress 6.0 and PHP 7.4 or newer.
Usage
Register an experiment. The first variant is the control:
add_action( 'init', function () {
ssab_register_experiment( 'hero-copy', array( 'control' => 50, 'short' => 50 ) );
} );
Keys may use lowercase letters, digits, - and _. Keep the variants in a stable order: changing their order or weights moves visitors between buckets.
In post content:
[ssab_variant experiment="hero-copy" name="control"]Everything you need to run your shop.[/ssab_variant]
[ssab_variant experiment="hero-copy" name="short"]Run your shop.[/ssab_variant]
In a template, using the helpers:
ssab_render_variant( 'hero-copy', array(
'control' => '<h1>Everything you need to run your shop.</h1>',
'short' => '<h1>Run your shop.</h1>',
) );
if ( 'short' === ssab_get_variant( 'hero-copy' ) ) {
get_template_part( 'parts/short-hero' );
}
The cookie must be sent before the page starts to print. The plugin finds the shortcode by itself, but it cannot see inside a template, so tell it which pages use the helpers:
add_filter( 'ssab_page_has_experiment', function ( $found ) {
return $found || is_front_page();
} );
A visitor who reaches a helper too late for a cookie sees the control, and no exposure is counted.
Report exposures to your analytics. This runs during page rendering, so keep it fast:
add_action( 'ssab_exposure', function ( $experiment, $variant, $visitor_id ) {
my_analytics_track( 'experiment_exposure', compact( 'experiment', 'variant', 'visitor_id' ) );
}, 10, 3 );
Respect a consent banner. Without consent the visitor sees the control and no cookie is set:
add_filter( 'ssab_can_set_cookie', 'my_visitor_has_consented' );
Make a preview link, or find ready-made ones under Tools, A/B previews:
$url = ssab_preview_url( 'hero-copy', 'short', home_url( '/pricing/' ), HOUR_IN_SECONDS );
Page caches
Every response from a page that runs an experiment is protected:
| Request | What the plugin sends |
|---|---|
| No cookie yet | nocache_headers(), and a new cookie |
| Has a cookie | Cache-Control: private, max-age=0 and Vary: Cookie |
| Preview link | nocache_headers() |
It also defines DONOTCACHEPAGE, which WordPress page-cache plugins honour.
That covers caches that respect these signals. You should still tell your cache to bypass any request carrying the cookie, so a stale copy can never be served to a bucketed visitor:
| Cache | Setting |
|---|---|
| WP Rocket | Advanced Rules, Never Cache Cookies: ssab_id |
| LiteSpeed Cache | Cache, Excludes, Do Not Cache Cookies: ssab_id |
| W3 Total Cache | Page Cache, Advanced, Rejected Cookies: ssab_id |
| Cloudflare | Cache Rule, when http.cookie contains "ssab_id": Bypass cache |
Nginx FastCGI cache:
if ($http_cookie ~* "ssab_id") { set $skip_cache 1; }
fastcgi_cache_bypass $skip_cache;
fastcgi_no_cache $skip_cache;
Varnish:
sub vcl_recv {
if (req.http.Cookie ~ "ssab_id") { return (pass); }
}
A cookie rule applies across the site, so a bucketed visitor misses the cache on every page. If that costs too much, exclude only the experiment's URLs from the cache instead. Either way, make sure the ssab_preview query string is not stripped or ignored by the cache.
Limitations
- A visitor can edit their own cookie and so choose a bucket. That is harmless for a marketing test, but do not use a variant to control access to anything.
- Exposures are counted per page view, so deduplicate by visitor id in your analytics.
- Crawlers are bucketed like anyone else.
Tests
composer install
composer test # both suites
vendor/bin/phpunit --testsuite unit # plain PHP only, no WordPress and no stubs
composer lint # WordPress Coding Standards
The glue suite runs the WordPress side against the small stubs in tests/glue/wp-stubs.php, not a full WordPress install, so try the plugin on a staging site before relying on it.
License
MIT