cheeztest/cheeztest.php at master · Automattic/cheeztest · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
<?php

/**
 * Plugin Name: CheezTest
 * Description: A class to help you create new Batcache-compatible server-side A/B tests
 * Author: ICHC, Automattic
 * Version: 1.0
 *
 * CheezTest Class - create new Batcache-compatible server-side A/B tests
 *
 * Main class from which all A/B tests are inherited. Enables fast setup
 * of A/B tests - upon initialization, the basic order of execution is:
 * set test name > check if user is qualified to participate >
 * get segment from either server or cookie > execute 'action' callback if present
 * > write segment cookie if neccessary
 *
 * User's qualification, segment, and group tests are done in batcache
 * so as to ensure correct cache variants are served.
 *
 * User's segment is assigned via client-side javascript. Mutliple test
 * segments are assigned at once - so if a user is qualified to participate
 * in more than one test, all segments are assigned at the same time. When
 * segments need to be set, a small javascript is injected into the <head>
 * via a call to CheezTest::write_segment_cookie(). This javascript sets a
 * cookie to retain the assigned segment.
 *
 * Test case data (name, is_qualified, & group) are stored in the $active_tests
 * static hash and made accessible via the 'is_qualified_for', 'get_group_for', and
 * 'is_in_group' static methods. This enables theme branching via:
 *
 * if ( CheezTest::is_qualified_for( 'my-example-test' ) {
 *     //test-specific stuff goes here
 * }
 *
 * - or -
 *
 * if ( CheezTest::is_in_group( 'my-example-test', 'my-example-group' ) ) {
 *    //group-specific stuff goes here
 * }
 *
 * @access	public
 * @author Matt Mirande, I Can Haz Cheezburger
 * @author Mohammad Jangda, Automattic
 *
 * @license GPL v2
 */
class CheezTest {

	public $name = '';
	public $group = null;
	public $is_qualified = true;
	private $expires = 0;
	/**
	* @access		public
	* @staticvar	array [ $active_tests ] key / val map with name, is_qualified,
	*				and group for all child objects. Enables easier accesss
	*				across the application via "is_qualified_for", etc helpers.
	*/
	public static $active_tests = array();

	private static $is_excluded = false;

	/**
	 * __construct - main constructor routine
	 *
	 * Configures and initiates an A/B test object.
	 *
	 * @access	public
	 * @param	array [ $opts ] key / value map containing configuration
	 *			options. Options include: name, expires, groups, action,
	 *			and is_qualified settings. The group property can optionally
	 *			contain a simple array of strings representing group names or each
	 *			group can be represented as an object with a 'threshold' property.
	 *			The 'threshold' will then be used to establish the group size -
	 *			e.g. 'threshold' => 10 indicates 10% of segments (segments 0 - 9)
	 *			will be assigned to this group.
	 *
	 */
	function __construct( $opts = array() ) {
		//exclude non-user requests
		if ( ! static::is_user_request() ){
			return;
		}

		$defaults = array(
			'name' =>  'ab-test',
			'expires' => 31536000, //how long the user's segment cookie will persist
			'groups' => array( 'seg-group-a', 'seg-group-b' ),
			'is_qualified' => '', //accepts string that will be evaluated as func by batcache.
			'action' => false //accepts anon-func e.g. function( $group ){} or false to bypass
		);

		//merge opts w/ defaults to establish child's configuration
		$cfg = array_merge( $defaults, $opts );

		$this->name = $cfg[ "name" ];

		//establish basic eligibility if 'is_qualified' is empty, all visitors are qualified to receive a segment
		if ( ! empty( $cfg[ 'is_qualified' ] ) && ! $this->qualify_user( $cfg[ "is_qualified" ] ) ) {
			return;
		}

		//establish user's group
		$this->group = $this->assign_group( $cfg[ "groups" ] );

		//add object's state to active tests collection to enable theme branching
		static::$active_tests[ $this->name ] = array(
			'is_qualified' => $this->is_qualified,
			'group' => $this->group
		);

		//fire 'action' callback if present
		if ( $this->group && is_callable( $cfg[ "action" ] ) ) {
			$cfg[ "action" ]( $this->group );
		}

		//if segment needs to be recorded in cookie, enqueue JS to do so
		if ( ! $this->has_segment_cookie() ) {
			$this->expires = $cfg[ 'expires' ] ? ( gmdate( 'r', time() + $cfg[ 'expires' ] ) ) : 0;
			add_action( 'wp_print_footer_scripts' , array( $this, 'write_segment_cookie' ), 1 );
		}
	}

	/**
	 * qualify_user - batcahe-friendly test to determine if user is qualified for test
	 *
	 * Determines if user is eligible to participate in AB test by
	 * running an arbitrary function body provided via $test argument.
	 * Result is stored within object via $this->is_qualified.
	 *
	 * @access	private
	 * @param	string [ $test ] function body used to determine user's
	 *			eligibility.
	 * @return  bool true if the user is eligible to participate
	 */
	private function qualify_user( $test ) {
		$this->is_qualified = static::run_vary_cache_func( $test );
		return $this->is_qualified;
	}

	/**
	 * has_segment_cookie - batcahe-friendly test to determine if user has a segment cookie
	 *
	 * @access	private
	 * @return  bool whether or not segment cookie exists
	 */
	private function has_segment_cookie(){
		$test = sprintf( 'return (bool) isset( $_COOKIE["%s"] );', $this->name );
		return static::run_vary_cache_func( $test );
	}

	/**
	 * assign_group - assign a segment group (e.g. A, B, etc)
	 *
	 * Determines what group the assigned segment belongs in and
	 * creates a batcache-friendly test to ensure proper variant
	 * is shown.
	 *
	 * If the user has a segment cookie, the segment in the cookie
	 * is returned. If not, the server returns a random group based
	 * on the thresholds provided in the test config.
	 *
	 * @access	private
	 * @param	array [ $groups ] key / value map which contains the
	 *			group names to use. Unless 'threshold' property is supplied
	 *			the count of the array's items determines how many possible
	 *			groups there are as well as each group's size.
	 * @return  string group assigned (as derived from $groups argument array)
	 */
	private function assign_group( $groups ){

		$segment_checks = array();
		$cookie_checks = array();
		$block_size = 100 / count( $groups );
		$block_end = $block_size;
		$block_start = 0;

		//loop through groups and build up test logic to determine group assignment
		foreach ( $groups as $group => $group_args ){

			//use 'threshold' to determine group sizing if available
			if ( isset( $group_args[ 'threshold' ] ) && is_array( $group_args ) ){
				$block_end = $block_start + ( int ) $group_args[ 'threshold' ];
			} else {
				$group = $groups[ $group ];
			}

			if ( $block_end > 100 ){
				$block_end = 100;
			}

			//setup batcache vary on cache conditions
			$segment_checks[] = sprintf(
				'( $seg_num >= %1$d && $seg_num < %2$d ) return "%3$s";',
				$block_start,
				$block_end,
				$group
			);

			$cookie_checks[] = sprintf(
				'( $_COOKIE["%1$s"] === "%2$s" ) return "%2$s";',
				$this->name,
				$group
			);

			//update block
			$block_start = $block_end;
			$block_end = $block_start + $block_size;
		}

		// Take array of checks and turn into string of if/then return statements
		$segment_checks_str = 'if' . implode( 'elseif', $segment_checks );
		$cookie_checks_str = 'if' . implode( 'elseif', $cookie_checks );

		$test = sprintf( 'if( isset( $_COOKIE["%1$s"] ) ){ %2$s } else { $seg_num = rand( 0,99 ); %3$s }', $this->name, $cookie_checks_str, $segment_checks_str );
		return static::run_vary_cache_func( $test );
	}

	/**
	 * run_vary_cache_func - environment-neutral interface to batcache's "vary_cache_on_function"
	 *
	 * Establishes whether or not to use a new cache variant by
	 * running an arbitrary function body provided via $test argument.
	 * $test is run both locally and in the batcache.
	 *
	 * @access	private
	 * @param	string [ $test ] function body used to determine user's
	 *			eligibility. Must be a string in order to work with
	 *			WP's batcache 'vary_cache_on_function' feature. Must
	 *			include one or more references to "$_" variables.
	 * @return  mixed (bool | string | int)
	 */
	private static function run_vary_cache_func( $test ){

		if ( preg_match('/include|require|echo|print|dump|export|open|sock|unlink|`|eval/i', $test) )
			trigger_error('Illegal word in cache variant function determiner.', E_USER_ERROR );

		if ( !preg_match('/\$_/', $test) )
			trigger_error('Cache variant function should refer to at least one $_ variable.', E_USER_ERROR );

		if ( function_exists( 'vary_cache_on_function' ) ) {
			vary_cache_on_function( $test );
		}

		$test_func = create_function( '', $test );
		return $test_func();
	}

	/**
	 * is_user_request - Determines if the request type is one typically made
	 * by a user
	 *
	 * Test whether or not the request being processed matches what would typically
	 * be made by a user. Cron jobs, requests for the admin section or feeeds, and
	 * any request made by google, ms/bing, or yahoo's slurp bot are flagged.
	 *
	 * @access	public
	 * @return	bool true if request appears to be user-generated
	 */
	private static function is_user_request(){
		//bail if we already know this request is not valid
		if ( static::$is_excluded ){
			return false;
		}

		$is_bot_test = 'return stripos( $_SERVER[ "HTTP_USER_AGENT" ], "googlebot" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "bingbot" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "msnbot" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "slurp" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "feedburner" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "facebook" ) !== false || ' .
			'stripos( $_SERVER[ "HTTP_USER_AGENT" ], "technoratisnoop" ) !== false;';

		$is_bot = static::run_vary_cache_func( $is_bot_test );

		if ( ( defined( 'DOING_CRON' ) && DOING_CRON )
			|| ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST )
			|| ( defined( 'WP_ADMIN' ) && WP_ADMIN )
			|| is_admin()
			|| $is_bot ) {
			static::$is_excluded = true;
			return false;
		}
		return true;
	}

	/**
	 * write_segment_cookie - serves javascript response to client to write the user's
	 * segment into a cookie so it will persist across visits
	 *
	 * @return
	 */
	function write_segment_cookie(){
		?>
			<script>
				( function(){

					// Check if cookies are enabled
					// @see http://sveinbjorn.org/cookiecheck
					var cookieEnabled = (navigator.cookieEnabled) ? true : false;

					if (typeof navigator.cookieEnabled == "undefined" && !cookieEnabled){
						document.cookie="testcookie";
						cookieEnabled = (document.cookie.indexOf("testcookie") != -1) ? true : false;
					}

					if( ! cookieEnabled )
						return;

					// Set cookie with test condition
					document.cookie = <?php echo json_encode( $this->name ); ?> + '=' + <?php echo json_encode( $this->group ); ?> + '; expires=' + <?php echo json_encode( $this->expires ); ?> + '; path=/';

				})();
			</script>
		<?php
	}

	/**
	 * is_qualified_for - Helper func to get user's eligibility for any active test
	 *
	 * Returns bool true if user is qualified to see test - usage:
	 *     if ( CheezTest::is_qualified_for( 'my-example-test' ) {
	 *         //test-specific stuff goes here
	 *     }
	 *
	 * @access	public
	 * @param	string [ $name ] test name assigned during child initialization
	 * @return  bool true if the user is eligible to participate (is qualified and has group)
	 */
	static function is_qualified_for( $name ){
		if ( array_key_exists( $name, static::$active_tests ) ) {
			return static::$active_tests[ $name ][ 'is_qualified' ] && static::$active_tests[ $name ][ 'group' ];
		}
		return false;
	}

	/**
	 * get_group_for - Helper func to get user's group assignment for any active test
	 *
	 * Returns 'group' property of static $active_tests collection
	 *
	 * @access	public
	 * @param	string [ $name ] test name assigned during child initialization
	 * @return  mixed (string | bool) group name if user is eligible, false if not
	 */
	static function get_group_for( $name ){
		if ( isset( static::$active_tests[ $name ] ) ) {
			return static::$active_tests[ $name ][ 'group' ];
		}
		return false;
	}

	/**
	 * is_in_group - Helper func to check if user is in the specified group
	 *
	 * @access	public
	 * @param	string [ $name ] test name assigned during child initialization
	 * @param	string [ $group ] group name to check against
	 * @return	bool true if user is in in test group, false if not
	 */
	static function is_in_group( $name, $group ) {
		return static::get_group_for( $name ) == $group;
	}
}