<?php
/* -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
# ***** BEGIN LICENSE BLOCK *****
# This file is part of Plume Framework, a simple PHP Application Framework.
# Copyright (C) 2001-2010 Loic d'Anterroches and contributors.
#
# Plume Framework is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation; either version 2.1 of the License, or
# (at your option) any later version.
#
# Plume Framework is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
#
# ***** END LICENSE BLOCK ***** */

/**
 * Core  A/B testing component.
 *
 * The two importants methods are `test` and `convert`.
 *
 * For performance reasons, the A/B testing component requires you to
 * setup a cache (APC or Memcached) and use the MongoDB database. The
 * amount of data in the MongoDB should not be that big for most of
 * the websites and as such it is fine if you are using the 32bit
 * version of MongoDB.
 *
 * For the moment the storage is not abstracted to use another database.
 *
 * All the configuration variables for the component start with
 * `pluf_ab_`. You need to add 'Pluf_AB' to your list of middleware.
 *
 */
class Pluf_AB
{
    /**
     * MongoDB database handler.
     */
    public static $db = null;

    /**
     * Returns an alternative for a given test.
     * 
     * The middleware is already storing the uid of the user and makes
     * it available as $request->pabuid.
     *
     * @param $test string Unique name of the test
     * @param $request Pluf_HTTP_Request
     * @param $alts array Alternatives to pick from (array(true,false))
     * @param $weights array Weights for the alternatives (null)
     * @param $desc string Optional description of the test ('')
     * @return mixed One value from $alts
     */
    public static function test($test, &$request, $alts=array(true,false), 
                                $weights=null, $desc='')
    {
        if (Pluf::f('pluf_ab_allow_force', false) and 
            isset($request->GET[$test])) {
            return $alts[$request->GET[$test]];
        }
        $db = self::getDb();
        // Get or set test
        $dtest = $db->tests->findOne(array('_id' => $test), 
                                     array('_id', 'active', 'winner'));
        if ($dtest == null) {
            $dtest = array('_id' => $test,
                           'creation_dtime' => gmdate('Y-m-d H:i:s', 
                                                      $request->time),
                           'desc' => $desc,
                           'alts' => $alts,
                           'exp' => 0,
                           'conv' => 0,
                           'active' => true);
            for ($i=0;$i<count($alts);$i++) {
                $dtest['expalt_'.$i] = 0;
                $dtest['convalt_'.$i] = 0;
            }
            $db->tests->update(array('_id'=>$test), $dtest,
                               array('upsert' => true));
        } elseif (!$dtest['active']) {
            // If test closed with given alternative, returns alternative
            return (isset($dtest['winner'])) ? $alts[$dtest['winner']] : $alts[0];
        }
        if (!isset($request->pabuid)) {
            $request->pabuid = self::getUid($request);
        }
        if ($request->pabuid == 'bot') {
            return $alts[0];
        }
        // If $request->pabuid in test, returns corresponding alternative
        $intest = $db->intest->findOne(array('_id' => $test.'##'.$request->pabuid), 
                                      array('_id', 'alt'));
        if ($intest) {
            return $alts[$intest['alt']];
        }
        // Else find alternative, store and return it
        if ($weights == null) {
            $weights = array_fill(0, count($alts), 1.0/count($alts));
        }
        $alt = self::weightedRand($weights);
        $intest = array('_id' => $test.'##'.$request->pabuid, 
                        'test' => $test,
                        'pabuid' => $request->pabuid, 
                        'first_dtime' => gmdate('Y-m-d H:i:s', 
                                                $request->time),
                        'alt' => $alt);
        $db->intest->update(array('_id' => $test.'##'.$request->pabuid),
                            $intest, array('upsert' => true));
        // Update the counts of the test
        $db->tests->update(array('_id' => $test), 
                           array('$inc' => array('exp' => 1, 
                                                 'expalt_'.$alt => 1)));
        return $alts[$alt];
    }

    /**
     * Mark a test as converted.
     *
     * A user which was not exposed to the test or a bot is not marked
     * as converted as it is not significant.
     *
     * @param $test string Test
     * @param $request Pluf_HTTP_Request
     */
    public static function convert($test, $request)
    {
        if (!isset($request->pabuid) or $request->pabuid == 'bot') {
            return;
        }
        $db = self::getDb();
        $id = $test.'##'.$request->pabuid;
        $intest = $db->intest->findOne(array('_id' => $id), 
                                       array('_id', 'alt'));
        if (!$intest) {
            // Not tested
            return;
        }
        $conv = $db->convert->findOne(array('_id' => $id)); 
        if ($conv) {
            // Already converted
            return;
        }
        $dtest = $db->tests->findOne(array('_id' => $test)); 
        if (!$dtest or !$dtest['active']) {
            return;
        }
        $conv = array(
                      '_id' => $id,
                      'test' => $test,
                      );
        $db->convert->update(array('_id' => $id), $conv, 
                             array('upsert' => true));
        // increment the test counters
        $db->tests->update(array('_id' => $test), 
                           array('$inc' => array('conv' => 1, 
                                                 'convalt_'.$intest['alt'] => 1)));
    }

    /**
     * Register a property set for the user.
     *
     * This allows you to segment your users with these properties.
     *
     * @param $request Pluf_HTTP_Request
     * @param $props array Properties
     */
    public static function register(&$request, $props) 
    {
        $pabuid = (isset($request->pabuid)) ? 
            $request->pabuid : 
            self::getUid($request);
        if ($pabuid == 'bot') {
            return;
        }
        $request->pabuid = $pabuid;
        $request->pabprops = array_merge($request->pabprops, $props);
    }

    /**
     * Track a funnel.
     *
     * The array of properties can be used to track different A/B
     * testing cases.
     *
     * The list of properties must be the same at all the steps of the
     * funnel, you cannot pass array('gender' => 'M') at step 1 and
     * array('age' => 32) at step 2. You need to pass both of them at
     * all steps.
     *
     * @param $funnel string Name of the funnel
     * @param $step int Step in the funnel, from 1 to n
     * @param $stepname string Readable name for the step
     * @param $request Pluf_HTTP_Request Request object
     * @param $props array Array of properties associated with the funnel (array())
     */
    public static function trackFunnel($funnel, $step, $stepname, $request, $props=array())
    {
        $pabuid = (isset($request->pabuid)) ? 
            $request->pabuid : 
            self::getUid($request);
        if ($pabuid == 'bot') {
            return;
        }
        $request->pabuid = $pabuid;
        $cache = Pluf_Cache::factory();
        $key = 'pluf_ab_funnel_'.crc32($funnel.'#'.$step.'#'.$pabuid);
        if ($cache->get($key, false)) {
            return; // The key is valid 60s not to track 2 steps within 60s
        }
        $cache->set($key, '1', 60);
        $what = array(
                      'f' => $funnel,
                      's' => $step,
                      'sn' => $stepname,
                      't' => (int) gmdate('Ymd', $request->time),
                      'u' => $pabuid,
                      'p' => array_merge($request->pabprops, $props),
                      );
        $db = self::getDb();
        $db->funnellogs->insert($what);
    }

    /**
     * Process the response of a view.
     *
     * If the request has no cookie and the request has a pabuid, set
     * the cookie in the response. 
     *
     * @param Pluf_HTTP_Request The request
     * @param Pluf_HTTP_Response The response
     * @return Pluf_HTTP_Response The response
     */
    function process_response($request, $response)
    {
        if (!isset($request->COOKIE['pabuid']) and isset($request->pabuid)
             and $request->pabuid != 'bot') {
            $response->cookies['pabuid'] = $request->pabuid;
        }
        if (isset($request->pabprops) and count($request->pabprops) 
            and $request->pabuid != 'bot') {
            $response->cookies['pabprops'] = Pluf_Sign::dumps($request->pabprops, null, true);
        }
        return $response;
    }

    /**
     * Process the request.
     *
     * If the request has the A/B test cookie, set $request->pabuid.
     *
     * @param Pluf_HTTP_Request The request
     * @return bool False
     */
    function process_request($request)
    {
        if (isset($request->COOKIE['pabuid']) and
            self::check_uid($request->COOKIE['pabuid'])) {
            $request->pabuid = $request->COOKIE['pabuid'];
        }
        $request->pabprops = array();
        if (isset($request->COOKIE['pabprops'])) {
            try {
                $request->pabprops = Pluf_Sign::loads($request->COOKIE['pabprops']);
            } catch (Exception $e) {
            }
        }
        return false;
    }

    /**
     * Get a MongoDB database handle.
     *
     * It opens only one connection per request and tries to keep a
     * persistent connection between the requests.
     *
     * The configuration keys used are:
     *
     * `pluf_ab_mongo_server`: 'mongodb://localhost:27017'
     * `pluf_ab_mongo_options`: array('connect' => true, 
     *                                'persist' => 'pluf_ab_mongo')
     * `pluf_ab_mongo_db`: 'pluf_ab'
     *
     * If you have a default installation of MongoDB, it should work
     * out of the box. 
     *
     */
    public static function getDb()
    {
       if (self::$db !== null) {
            return self::$db;
        }
        $server = Pluf::f('pluf_ab_mongo_server', 'mongodb://localhost:27017');
        $options = Pluf::f('pluf_ab_mongo_options', 
                           array('connect' => true, 'persist' => 'pluf_ab_mongo'));
        $conn = new Mongo($server, $options); 
        self::$db = $conn->selectDB(Pluf::f('pluf_ab_mongo_db', 'pluf_ab'));
        return self::$db;
    }
    
    /**
     * Get the uid of a given request.
     *
     * @param $request Pluf_HTTP_Request
     */
    public static function getUid($request)
    {
        if (isset($request->COOKIE['pabuid']) and 
            self::check_uid($request->COOKIE['pabuid'])) {
            return $request->COOKIE['pabuid'];
        }
        if (!isset($request->SERVER['HTTP_USER_AGENT']) or
            self::isBot($request->SERVER['HTTP_USER_AGENT'])) {
            return 'bot';
        }
        // Here we need to make an uid, first check if a user with
        // same ip/agent exists and was last seen within the last 1h.
        // We get that from MemcacheDB
        $cache = Pluf_Cache::factory();
        $key = 'pluf_ab_'.crc32($request->remote_addr.'#'.$request->SERVER['HTTP_USER_AGENT']);
        if ($uid=$cache->get($key, null)) {
            $cache->set($key, $uid, 3600);
            return $uid;
        }
        $uid = self::make_uid($request);
        $cache->set($key, $uid, 3600);
        return $uid;
    }

    /**
     * Check if a given user agent is a bot.
     *
     * @param $user_agent string User agent string
     * @return bool True if the user agent is a bot
     */
    public static function isBot($user_agent)
    {
        static $bots = array('robot', 'checker', 'crawl', 'discovery', 
                             'hunter', 'scanner', 'spider', 'sucker', 'larbin',
                             'slurp', 'libwww', 'lwp', 'yandex', 'netcraft',
                             'wget', 'twiceler');
        static $pbots = array('/bot[\s_+:,\.\;\/\\\-]/i', 
                              '/[\s_+:,\.\;\/\\\-]bot/i');
        foreach ($bots as $r) {
            if (false !== stristr($user_agent, $r)) {
                return true;
            }
        }
        foreach ($pbots as $p) {
            if (preg_match($p, $user_agent)) {
                return true;
            }
        }
        if (false === strpos($user_agent, '(')) {
            return true;
        }
        return false;
    }

    /**
     * Returns a random weighted alternative.
     *
     * Given a series of weighted alternative in the format:
     * 
     * <pre>
     * array('alt1' => 0.2,
     *       'alt2' => 0.3,
     *       'alt3' => 0.5);
     * </pre>
     *
     * Returns the key of the selected alternative. In the following
     * example, the alternative 3 (alt3) has a 50% chance to be
     * selected, if the selected the results would be 'alt3'.

     * @link: http://20bits.com/downloads/w_rand.phps
     *
     * @param $weights array Weighted alternatives
     * @return mixed Key of the selected $weights array
     */
    public static function weightedRand($weights) 
    {
        $r = mt_rand(1,10000);
        $offset = 0;
        foreach ($weights as $k => $w) {
            $offset += $w*10000;
            if ($r <= $offset) {
                return $k;
            }
        }
    }

    /**
     * Given a request, make a corresponding A/B test UID.
     *
     * The UID is based on the time, the remote address, a random
     * component and is hashed to ensure the integrity and avoid the
     * need of a database hit when controlled.
     *
     * @param $request Pluf_HTTP_Request
     * @return string UID
     */
    public static function make_uid($request)
    {
        $base = sprintf('%08X%08X%08X', $request->time, 
                        sprintf('%u', crc32($request->remote_addr)), 
                        rand());
        return sprintf('%s%08X', $base, sprintf('%u', crc32($base.md5(Pluf::f('secret_key')))));
    }

    /**
     * Validate the uid in the cookie. 
     *
     * @see self::make_uid
     *
     * @param $uid string The UID
     * @return bool True if the UID is valid
     */
    public static function check_uid($uid)
    {
        if (strlen($uid) != 32) {
            return false;
        }
        $check = sprintf('%08X', sprintf('%u', crc32(substr($uid, 0, 24).md5(Pluf::f('secret_key')))));
        return  ($check == substr($uid, -8));
    }

    /* ------------------------------------------------------------
     *
     *                  Statistics Functions
     *
     * Note: I am not a statistician, use at your own risk!
     *
     * ------------------------------------------------------------ */

    /**
     * Given a conversion rate calculate the recommended sample sizes.
     *
     * The sample sizes is calculated to be significant at 95% in the
     * case of a variation of conversion with respect to the other
     * alternative of 25%, 15% and 5%.
     *
     * @param $conv Conversion rate ]0.0;1.0]
     * @return array The 3 sample sizes for 25%, 15% and 5%
     */
    public static function ssize($conv)
    {
        $a = 3.84145882689; // $a = pow(inverse_ncdf(1-(1-0.95)/2),2)
        $res = array();
        $bs = array(0.0625, 0.0225, 0.0025);
        foreach ($bs as $b) {
            $res[] = (int) ((1-$conv)*$a/($b*$conv));
        }
        return $res;
    }


    /**
     * Given a test, returns the corresponding stats.
     *
     * @param $test array Test definition and results
     * @return array Statistics for the test
     */
    public static function getTestStats($test)
    {
        $stats = array(); // Will store the stats
        $n = count($test['alts']);
        $aconvr = array(); // All the conversion rates to sort the alternatives
        for ($i=0;$i<$n;$i++) {
            $conv = (isset($test['convalt_'.$i])) ? $test['convalt_'.$i] : 0;
            $exp = (isset($test['expalt_'.$i])) ? $test['expalt_'.$i] : 0;
            $convr = self::cr(array($exp, $conv));
            $nconvr =  ($convr !== null) ?
                sprintf('%01.2f%%', $convr*100.0) : 'N/A';
            $ssize = ($convr !== null and $convr > 0) ?
                self::ssize($convr) : array();
            $stats[] = array('alt' => $i,
                             'convr' => $convr,
                             'conv' => $conv,
                             'exp' => $exp,
                             'nconvr' => $nconvr,
                             'ssize' => $ssize);
            $aconvr[] = ($convr === null) ? 0 : $convr;
        }
        array_multisort($aconvr, SORT_DESC, $stats);
        // We want the best to be significantly better than the second best.
        for ($i=0;$i<$n;$i++) {
            $convr = $stats[$i]['convr'];
            $exp = $stats[$i]['exp'];
            $conv = $stats[$i]['conv'];
            $comp = false;
            $zscore = false;
            $conf = false;
            $better = false;
            if ($i != 1 and $stats[1]['convr'] > 0) {
                // Compare with base case and get confidence/Z-score
                $comp = 100.0 * (float) ($convr - $stats[1]['convr'])/ (float) ($stats[1]['convr']);
                if ($comp > 0) $better = true;
                $comp = sprintf('%01.2f%%', $comp);                
                $zscore = self::zscore(array($stats[1]['exp'], $stats[1]['conv']), 
                                       array($exp, $conv));
                $conf = sprintf('%01.2f%%', self::cumnormdist($zscore)*100.0);
                $zscore = sprintf('%01.2f', $zscore);
            }
            $stats[$i]['comp'] = $comp;
            $stats[$i]['zscore'] = $zscore;
            $stats[$i]['conf'] = $conf;
            $stats[$i]['better'] = $better;
        }
        return $stats;
    }

    public static function cr($t) 
    { 
        if ($t[1] < 0) return null;
        if ($t[0] <= 0) return null;
        return $t[1]/$t[0]; 
    }

    public static function zscore($c, $t) 
    {
        $z = self::cr($t)-self::cr($c);
        $s = (self::cr($t)*(1-self::cr($t)))/$t[0] 
            + (self::cr($c)*(1-self::cr($c)))/$c[0];
        return $z/sqrt($s);
    }

    /**
     * Approximation of the cumulative normal distribution.
     */
    public static function cumnormdist($x)
    {
        $b1 =  0.319381530;
        $b2 = -0.356563782;
        $b3 =  1.781477937;
        $b4 = -1.821255978;
        $b5 =  1.330274429;
        $p  =  0.2316419;
        $c  =  0.39894228;

        if($x >= 0.0) {
            $t = 1.0 / ( 1.0 + $p * $x );
            return (1.0 - $c * exp( -$x * $x / 2.0 ) * $t *
                    ( $t *( $t * ( $t * ( $t * $b5 + $b4 ) + $b3 ) + $b2 ) + $b1 ));
        } else {
            $t = 1.0 / ( 1.0 - $p * $x );
            return ( $c * exp( -$x * $x / 2.0 ) * $t *
                     ( $t *( $t * ( $t * ( $t * $b5 + $b4 ) + $b3 ) + $b2 ) + $b1 ));
        }
    }
}