Overview

Namespaces

  • Apptus
    • ESales
      • Connector
        • Report
        • Time
    • Util
      • Cache
  • PHP
  • Overview
  • Namespace
  • Class
  • Tree
  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: 365: 366: 367: 368: 369: 370: 371: 372: 373: 374: 375: 376: 377: 378: 379: 
<?php
namespace Apptus\ESales\Connector;

/**
 * A session where information is exchanged with an eSales service.
 *
 * Use the notification methods to notify the eSales service about client-side activities. These notification will be used to
 * improve results from eSales with the use of machine learning algorithms, and for statistical reports. <br>
 * A tutorial section describing the procedure for notifying client-side activities can be found in the tutorial section
 * <i>Notifying Customer Actions</i> on <a href="http://zone.apptus.com">Apptus Zone</a> (http://zone.apptus.com).
 *
 * Use the {@see Session::panel()} method to get a {@see Panel} object, from which you may retrieve content from the eSales service.
 *
 * You may (but need not) call the {@see Session::end()} method once the session is over. This will allow the eSales service to include
 * the information in statistical reports.
 *
 * The session will end automatically when neither a panel has been retrieved, nor a notifications has been sent, within 15
 * minutes.
 */
class Session {
    /* @internal */
    const CUSTOMER_KEY_HEADER_NAME = 'eSales-customer_key';
    /* @internal */
    const MARKET_HEADER_NAME = 'eSales-market';
    /* @internal */
    const PROPERTY_MARKET = 'market';
    /* @internal */
    const PROPERTY_CUSTOMER_KEY = 'customer_key';

    private $key;
    private $secureCluster;
    private $cluster;
    private $customerKey;
    private $market;
    private $ended = false;
    private $timestamp = null; // Only used for system tests

    /**
     * @internal
     * @param string $sessionKey
     * @param Cluster $secureCluster
     * @param Cluster $cluster
     * @param string $customerKey
     * @param string $market
     */
    public function __construct($sessionKey, Cluster $secureCluster, Cluster $cluster, $customerKey = null, $market = null) {
        $this->key = (string) $sessionKey;
        $this->secureCluster = $secureCluster;
        $this->cluster = $cluster;
        $this->customerKey = $customerKey;
        $this->market = $market;
    }

    /**
     * @internal
     * Set timestamp of current session. NOTE: should only be used
     * for system test.
     *
     * @param long $timestamp
     *            Custom timestamp, only used for system tests
     */
    public function setTimestamp($timestamp) {
        $this->timestamp = $timestamp;
    }

    /**
     * Returns a panel specified by the path supplied as argument.
     *
     * @param string
     *            The path of the panel
     * @return Panel
     *            A panel object with the specified path.
     */
    public function panel($path) {
        return new Panel($this->cluster, $this, $path);
    }

    /**
     * Creates a dynamic page with the specified name.
     *
     * @param name
     *          The name of the panel
     * @return DynamicPage
     *          A dynamic page object with the specified name
     */
    public function dynamicPage($name) {
        return new DynamicPage($this->cluster, $this, $name);
    }

    /**
     * @internal
     * @param string
     * @param ArgMap|array
     */
    protected function _notify($type, $params, $cluster) {
        $params['session_key'] = $this->key;
        if ($this->timestamp !== null) {
            $params['timestamp_for_testing'] = (string) $this->timestamp;
        }
        $headers = new ArgMap();
        if ($this->market() !== null) {
            $headers->put(self::MARKET_HEADER_NAME, $this->market);
        }
        if ($this->customerKey() !== null) {
            $headers->put(self::CUSTOMER_KEY_HEADER_NAME, $this->customerKey);
        }
        $cluster->notify($type, $params, $headers);
    }

    /**
     * Sends a notification to the eSales service, about a session property being set.
     *
     * Later calls will overwrite the previous values of the property.
     *
     * @param string
     *            The name of the property. Any valid Java identifier may be used.
     * @param string
     *            The value of the property.
     * @throws RequestFailedException
     *             if the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *             if name or value is null or empty
     */
    public function notifyProperty($name, $value) {
        if ($name === null || $name === '') {
            throw new \InvalidArgumentException('name cannot be null or empty.');
        }
        if ($value === null || $value === '') {
            throw new \InvalidArgumentException('value cannot be null or empty.');
        }

        if ($name == self::PROPERTY_MARKET) {
            $this->market = $value;
        } else if ($name == self::PROPERTY_CUSTOMER_KEY) {
            $this->customerKey = $value;
        }

        $this->_notify('/property', array(
            'name' => (string) $name,
            'value' => (string) $value,
        ), $this->cluster);
    }

    /**
     * Sends a notification to the eSales service, about a click being made by the user in a session.
     *
     * @param string
     *            The ticked for the object that was clicked.
     * @throws RequestFailedException
     *             if the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *             if ticket is null or empty
     */
    public function notifyClick($ticket) {
        if ($ticket === null || $ticket === '') {
            throw new \InvalidArgumentException('ticket cannot be null or empty.');
        }
        $this->_notify('/click', array(
            'ticket' => (string) $ticket,
        ), $this->cluster);
    }

    /**
     * Sends a notification to the eSales service, about a product being added to the shopping cart by a user in the session.
     *
     * @param string
     *            The ticked for the object that was added to the cart.
     *
     * @throws RequestFailedException
     *             if the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *             if ticket is null or empty
     */
    public function notifyAddingToCart($ticket) {
        if ($ticket === null || $ticket === '') {
            throw new \InvalidArgumentException('ticket cannot be null or empty.');
        }
        $this->_notify('/adding_to_cart', array(
            'ticket' => (string) $ticket,
        ), $this->cluster);
    }

     /**
     * Sends a notification to the eSales service, about a non-eSales product click being made by the user in a session. This
     * method should only be used on non-eSales rendered products where no ticket is available.
     *
     * @param string
     *              The product key of the clicked product or may be null if you have a variant key.
     * @param string
     *              The variant key of the clicked variant or null if it is a click on a product only.
     * @throws RequestFailedException
     *              If the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *              If productKey or variantKey are empty or both are null.
     */
    public function notifyNonEsalesClick($productKey, $variantKey) {
        $argMap = $this->fillProductArguments($productKey, $variantKey, 'click');
        $this->_notify('/non_esales_click', $argMap, $this->cluster);
    }

     /**
     * Sends a notification to the eSales service, about a non-eSales product being added to the shopping cart by a user in the
     * session. This method should only be used on non-eSales rendered products where no ticket is available.
     *
     * @param string
     *              The product key of the added to cart product or may be null if you have a variant key.
     * @param string
     *              The variant key of the variant or null if it is an add to cart on a product only.
     * @throws RequestFailedException
     *              If the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *              If productKey or variantKey are empty or both are null.
     */
     public function notifyNonEsalesAddingToCart($productKey, $variantKey) {
         $argMap = $this->fillProductArguments($productKey, $variantKey, 'adding_to_cart');
         $this->_notify('/non_esales_adding_to_cart', $argMap, $this->cluster);
    }

    /**
     * Sends a notification to the eSales service, about products and variants being paid by a user in the session.
     *
     * @param Order
     *            Order containing the paid products and variants.
     * @throws RequestFailedException if the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *             if order is null or empty
     */
    public function notifyPayment(Order $order) {
        $serializedOder = $order->serialize();
        if ($serializedOder === '') {
            throw new \InvalidArgumentException('order cannot be empty.');
        }
        $this->_notify('/payment', array (
            'order' => $serializedOder,
        ), $this->secureCluster);
    }

    /**
     * Sends a notification to the eSales service, about a product being rated.
     *
     * @param string
     *            The key of the rated product.
     * @param int
     *            The rating.
     * @throws RequestFailedException
     *             if the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *             if rating is not numeric or if productKey is null or empty
     */
    public function notifyRating($productKey, $rating) {
        if ($productKey === null || $productKey === '') {
            throw new \InvalidArgumentException('productKey cannot be null or empty.');
        }
        if (!is_int($rating)) {
            throw new \InvalidArgumentException('rating must be an int.');
        }
        $this->_notify('/rating', array(
            'product_key' => $productKey,
            'rating' => (string) $rating,
        ), $this->cluster);
    }

    private function notifyEnd() {
        $this->_notify('/end', array(), $this->cluster);
    }

    /**
     * Notifies the eSales service that the session has ended, and free all resources used by the session on the client-side.
     *
     * @return boolean
     *              True if the notification has been sent successfully, false otherwise.
     */
    public function end() {
        try {
            if (!$this->ended) {
                $this->notifyEnd();
                $this->ended = true;
            }
            return $this->ended;
        } catch (ClusterUnavailableException $e) {
            return false;
        }
    }

    /**
     * Sends a notification to the eSales service, about a product being added to favorites.
     *
     * @param string
     *              The product key of the favorite product or may be null if you have a variant key.
     * @param string
     *              The variant key of the favorite. Can be null if a product key is provided. The variant key should always be set if the product has variants.
     * @throws RequestFailedException
     *              If the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *              If productKey or variantKey are empty or both are null.
     */
    public function notifyFavoriteAddition($productKey, $variantKey) {
        $this->notifyFavorite($productKey, $variantKey, false);
    }

    /**
     * Sends a notification to the eSales service, about a product being removed from favorites.
     *
     * @param string
     *              The product key of the favorite product or may be null if you have a variant key.
     * @param string
     *              The variant key of the favorite. Can be null if a product key is provided. The variant key should always be set if the product has variants.
     * @throws RequestFailedException
     *              If the notification cannot be sent to the eSales service.
     * @throws \InvalidArgumentException
     *              If productKey or variantKey are empty or both are null.
     */
    public function notifyFavoriteRemoval($productKey, $variantKey) {
        $this->notifyFavorite($productKey, $variantKey, true);
    }

    private function notifyFavorite($productKey, $variantKey, $remove) {
        $argMap = $this->fillProductArguments($productKey, $variantKey, 'favorite');
        $argMap['remove'] = $remove ? 'true' : 'false';
        $this->_notify('/favorite', $argMap, $this->cluster);
    }

    private function fillProductArguments($productKey, $variantKey, $name) {
        $argMap = array();
        if ($productKey === null) {
            if ($variantKey === null) {
                throw new \InvalidArgumentException('productKey and variantKey cannot both be null.');
            }
            if ($variantKey === '') {
                throw new \InvalidArgumentException('variantKey cannot be empty, set it to null if it is a '.$name.' on only the product.');
            }
            $argMap['variant_key'] = (string) $variantKey;
        } else if ($productKey === '') {
            throw new \InvalidArgumentException('productKey cannot be empty, set it to null if you only have the variantKey.');
        } else {
            if ($variantKey !== null && $variantKey === '') {
                throw new \InvalidArgumentException('variantKey cannot be empty, set it to null if it is a '.$name.' on only the product.');
            }
            $argMap['product_key'] = (string) $productKey;

            if ($variantKey !== null) {
                $argMap['variant_key'] = (string) $variantKey;
            }
        }

        return $argMap;
    }

    /**
     * Returns the session key.
     *
     * @return string
     *            The session key.
     */
    public final function key() {
        return $this->key;
    }

    /**
     * Returns the market.
     *
     * @return string
     *            The market.
     */
    public final function market() {
        return $this->market;
    }

    /**
     * Returns the customer key.
     *
     * @return string
     *            The customer key.
     */
    public final function customerKey() {
        return $this->customerKey;
    }
}
Apptus ESales Connector PHP API documentation generated by ApiGen