Make the timestamp parameter optional for interaction additions - default is the current time

Author: OndraFiedler

src/RecommApi/Requests/AddBookmark.php

@@ -23,7 +23,7 @@ class AddBookmark extends Request {
      */
     protected $item_id;
     /**
-     * @var string|float $timestamp Unix timestamp of the bookmark. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
+     * @var string|float $timestamp UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      */
     protected $timestamp;
     /**
@@ -39,22 +39,24 @@ class AddBookmark extends Request {
      * Construct the request
      * @param string $user_id User who bookmarked the item
      * @param string $item_id Bookmarked item
-     * @param string|float $timestamp Unix timestamp of the bookmark. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
+     *     - *timestamp*
+     *         - Type: string|float
+     *         - Description: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      *     - *cascadeCreate*
      *         - Type: bool
      *         - Description: Sets whether the given user/item should be created if not present in the database.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
-    public function __construct($user_id, $item_id, $timestamp, $optional = array()) {
+    public function __construct($user_id, $item_id, $optional = array()) {
         $this->user_id = $user_id;
         $this->item_id = $item_id;
-        $this->timestamp = $timestamp;
+        $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('cascadeCreate');
+        $existing_optional = array('timestamp','cascadeCreate');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -95,7 +97,8 @@ public function getBodyParameters() {
         $p = array();
         $p['userId'] = $this->user_id;
         $p['itemId'] = $this->item_id;
-        $p['timestamp'] = $this->timestamp;
+        if (isset($this->optional['timestamp']))
+             $p['timestamp'] = $this-> optional['timestamp'];
         if (isset($this->optional['cascadeCreate']))
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         return $p;

src/RecommApi/Requests/AddCartAddition.php

@@ -23,7 +23,7 @@ class AddCartAddition extends Request {
      */
     protected $item_id;
     /**
-     * @var string|float $timestamp Unix timestamp of the cart addition. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
+     * @var string|float $timestamp UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      */
     protected $timestamp;
     /**
@@ -39,22 +39,24 @@ class AddCartAddition extends Request {
      * Construct the request
      * @param string $user_id User who added the item to the cart
      * @param string $item_id Item added to the cart
-     * @param string|float $timestamp Unix timestamp of the cart addition. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
+     *     - *timestamp*
+     *         - Type: string|float
+     *         - Description: UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      *     - *cascadeCreate*
      *         - Type: bool
      *         - Description: Sets whether the given user/item should be created if not present in the database.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
-    public function __construct($user_id, $item_id, $timestamp, $optional = array()) {
+    public function __construct($user_id, $item_id, $optional = array()) {
         $this->user_id = $user_id;
         $this->item_id = $item_id;
-        $this->timestamp = $timestamp;
+        $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('cascadeCreate');
+        $existing_optional = array('timestamp','cascadeCreate');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -95,7 +97,8 @@ public function getBodyParameters() {
         $p = array();
         $p['userId'] = $this->user_id;
         $p['itemId'] = $this->item_id;
-        $p['timestamp'] = $this->timestamp;
+        if (isset($this->optional['timestamp']))
+             $p['timestamp'] = $this-> optional['timestamp'];
         if (isset($this->optional['cascadeCreate']))
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         return $p;

src/RecommApi/Requests/AddDetailView.php

@@ -23,7 +23,7 @@ class AddDetailView extends Request {
      */
     protected $item_id;
     /**
-     * @var string|float $timestamp Unix timestamp of the view. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
+     * @var string|float $timestamp UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      */
     protected $timestamp;
     /**
@@ -43,9 +43,11 @@ class AddDetailView extends Request {
      * Construct the request
      * @param string $user_id User who viewed the item
      * @param string $item_id Viewed item
-     * @param string|float $timestamp Unix timestamp of the view. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
+     *     - *timestamp*
+     *         - Type: string|float
+     *         - Description: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      *     - *duration*
      *         - Type: int
      *         - Description: Duration of the view
@@ -54,15 +56,15 @@ class AddDetailView extends Request {
      *         - Description: Sets whether the given user/item should be created if not present in the database.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
-    public function __construct($user_id, $item_id, $timestamp, $optional = array()) {
+    public function __construct($user_id, $item_id, $optional = array()) {
         $this->user_id = $user_id;
         $this->item_id = $item_id;
-        $this->timestamp = $timestamp;
+        $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->duration = isset($optional['duration']) ? $optional['duration'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('duration','cascadeCreate');
+        $existing_optional = array('timestamp','duration','cascadeCreate');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -103,7 +105,8 @@ public function getBodyParameters() {
         $p = array();
         $p['userId'] = $this->user_id;
         $p['itemId'] = $this->item_id;
-        $p['timestamp'] = $this->timestamp;
+        if (isset($this->optional['timestamp']))
+             $p['timestamp'] = $this-> optional['timestamp'];
         if (isset($this->optional['duration']))
              $p['duration'] = $this-> optional['duration'];
         if (isset($this->optional['cascadeCreate']))

src/RecommApi/Requests/AddPurchase.php

@@ -23,7 +23,7 @@ class AddPurchase extends Request {
      */
     protected $item_id;
     /**
-     * @var string|float $timestamp Unix timestamp of the purchase. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
+     * @var string|float $timestamp UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      */
     protected $timestamp;
     /**
@@ -39,22 +39,24 @@ class AddPurchase extends Request {
      * Construct the request
      * @param string $user_id User who purchased the item
      * @param string $item_id Purchased item
-     * @param string|float $timestamp Unix timestamp of the purchase. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
+     *     - *timestamp*
+     *         - Type: string|float
+     *         - Description: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      *     - *cascadeCreate*
      *         - Type: bool
      *         - Description: Sets whether the given user/item should be created if not present in the database.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
-    public function __construct($user_id, $item_id, $timestamp, $optional = array()) {
+    public function __construct($user_id, $item_id, $optional = array()) {
         $this->user_id = $user_id;
         $this->item_id = $item_id;
-        $this->timestamp = $timestamp;
+        $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('cascadeCreate');
+        $existing_optional = array('timestamp','cascadeCreate');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -95,7 +97,8 @@ public function getBodyParameters() {
         $p = array();
         $p['userId'] = $this->user_id;
         $p['itemId'] = $this->item_id;
-        $p['timestamp'] = $this->timestamp;
+        if (isset($this->optional['timestamp']))
+             $p['timestamp'] = $this-> optional['timestamp'];
         if (isset($this->optional['cascadeCreate']))
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         return $p;

src/RecommApi/Requests/AddRating.php

@@ -23,7 +23,7 @@ class AddRating extends Request {
      */
     protected $item_id;
     /**
-     * @var string|float $timestamp Unix timestamp of the rating. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
+     * @var string|float $timestamp UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      */
     protected $timestamp;
     /**
@@ -43,24 +43,26 @@ class AddRating extends Request {
      * Construct the request
      * @param string $user_id User who submitted the rating
      * @param string $item_id Rated item
-     * @param string|float $timestamp Unix timestamp of the rating. If you don't have the timestamp value available, you may use some artificial value, such as 0. It is preferable, however, to provide the timestamp whenever possible as the user's preferences may evolve over time.
      * @param float $rating Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
+     *     - *timestamp*
+     *         - Type: string|float
+     *         - Description: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
      *     - *cascadeCreate*
      *         - Type: bool
      *         - Description: Sets whether the given user/item should be created if not present in the database.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
-    public function __construct($user_id, $item_id, $timestamp, $rating, $optional = array()) {
+    public function __construct($user_id, $item_id, $rating, $optional = array()) {
         $this->user_id = $user_id;
         $this->item_id = $item_id;
-        $this->timestamp = $timestamp;
         $this->rating = $rating;
+        $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('cascadeCreate');
+        $existing_optional = array('timestamp','cascadeCreate');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -101,8 +103,9 @@ public function getBodyParameters() {
         $p = array();
         $p['userId'] = $this->user_id;
         $p['itemId'] = $this->item_id;
-        $p['timestamp'] = $this->timestamp;
         $p['rating'] = $this->rating;
+        if (isset($this->optional['timestamp']))
+             $p['timestamp'] = $this-> optional['timestamp'];
         if (isset($this->optional['cascadeCreate']))
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         return $p;

tests/AddBookmarkTest.php

@@ -4,8 +4,8 @@
 
 class AddBookmarkTest extends AddInteractionTestCase {
 
-    protected function createRequest($user_id, $item_id, $timestamp, $optional=array()) {
-        return new AddBookmark($user_id, $item_id, $timestamp, $optional);
+    protected function createRequest($user_id, $item_id, $optional=array()) {
+        return new AddBookmark($user_id, $item_id, $optional);
     }
 }
 ?>

tests/AddCartAdditionTest.php

@@ -4,8 +4,8 @@
 
 class AddCartAdditionTest extends AddInteractionTestCase {
 
-    protected function createRequest($user_id, $item_id, $timestamp, $optional=array()) {
-        return new AddCartAddition($user_id, $item_id, $timestamp, $optional);
+    protected function createRequest($user_id, $item_id, $optional=array()) {
+        return new AddCartAddition($user_id, $item_id, $optional);
     }
 }
 ?>

tests/AddDetailViewTest.php

@@ -4,8 +4,8 @@
 
 class AddDetailViewTest extends AddInteractionTestCase {
 
-    protected function createRequest($user_id, $item_id, $timestamp, $optional=array()) {
-        return new AddDetailView($user_id, $item_id, $timestamp, $optional);
+    protected function createRequest($user_id, $item_id, $optional=array()) {
+        return new AddDetailView($user_id, $item_id, $optional);
     }
 }
 ?>

tests/AddInteractionTestCase.php

@@ -6,22 +6,26 @@
 
 abstract class AddInteractionTestCase extends RecombeeTestCase {
 
-    abstract protected function createRequest($user_id, $item_id, $timestamp, $optional = array());
+    abstract protected function createRequest($user_id, $item_id, $optional = array());
 
     public function testAddInteraction() {
 
         //does not fail with cascadeCreate
-        $req = $this->createRequest('u_id', 'i_id', 0, ['cascadeCreate' => True]);
+        $req = $this->createRequest('u_id', 'i_id', ['cascadeCreate' => True]);
+        $this->client->send($req);
+
+        //does not fail with valid timestamp
+        $req = $this->createRequest('u_id', 'i_id', ['cascadeCreate' => True, 'timestamp' => '2013-10-29T09:38:41.341Z']);
         $this->client->send($req);
 
         //does not fail with existing item and user
-        $req = $this->createRequest('entity_id', 'entity_id', 0);
+        $req = $this->createRequest('entity_id', 'entity_id');
         $this->client->send($req);
 
         //fails with nonexisting item id
         try {
 
-            $req = $this->createRequest('entity_id', 'notexisting_id', 0);
+            $req = $this->createRequest('entity_id', 'notexisting_id');
             $this->client->send($req);
             throw new \Exception('Exception was not thrown');
         }
@@ -32,7 +36,7 @@ public function testAddInteraction() {
 
         //fails with nonexisting user id
         try {
-            $req = $this->createRequest('notexisting_id', 'entity_id', 0);
+            $req = $this->createRequest('notexisting_id', 'entity_id');
             $this->client->send($req);
             throw new \Exception('Exception was not thrown');
         }
@@ -43,7 +47,7 @@ public function testAddInteraction() {
 
         //fails with invalid time
         try {
-            $req = $this->createRequest('entity_id', 'entity_id', -15);
+            $req = $this->createRequest('entity_id', 'entity_id', ['timestamp' => -15]);
             $this->client->send($req);
             throw new \Exception('Exception was not thrown');
         }
@@ -54,7 +58,7 @@ public function testAddInteraction() {
 
         //really stores interaction to the system
         try {
-            $req = $this->createRequest('entity_id', 'entity_id', 0);
+            $req = $this->createRequest('u_id', 'i_id',  ['timestamp' => '2013-10-29T09:38:41.341Z']);
             $this->client->send($req);
             throw new \Exception('Exception was not thrown');
         }

tests/AddPurchaseTest.php

@@ -4,8 +4,8 @@
 
 class AddPurchaseTest extends AddInteractionTestCase {
 
-    protected function createRequest($user_id, $item_id, $timestamp, $optional=array()) {
-        return new AddPurchase($user_id, $item_id, $timestamp, $optional);
+    protected function createRequest($user_id, $item_id, $optional=array()) {
+        return new AddPurchase($user_id, $item_id, $optional);
     }
 }
 ?>