Support setting the region of your DB. Added Update / Delete More Ite…

…ms endpoints. Breaking changes: Client constructor: protocol parameter (HTTP/HTTPS) moved to options. Removed deprecated endpoints Item Based Recommendation and User Based Recommendation.
recombee · Apr 20, 2022 · 03a4762 · 03a4762
1 parent 9ea2b6c
commit 03a4762
Show file tree

Hide file tree

Showing 21 changed files with 305 additions and 692 deletions.
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ or
 ```
 {
     "require": {
-        "recombee/php-api-client": "^3.2.0"
+        "recombee/php-api-client": "^4.0.0"
     }
 }
 ```
@@ -30,7 +30,7 @@ use Recombee\RecommApi\Client;
 use Recombee\RecommApi\Requests as Reqs;
 use Recombee\RecommApi\Exceptions as Ex;
 
-$client = new Client('--my-database-id--', '--db-private-token--');
+$client = new Client('--my-database-id--', '--db-private-token--', ['region' => 'us-west']);
 
 const NUM = 100;
 const PROBABILITY_PURCHASED = 0.1;
@@ -77,7 +77,7 @@ use Recombee\RecommApi\Exceptions as Ex;
 const NUM = 100;
 const PROBABILITY_PURCHASED = 0.1;
 
-$client = new Client('--my-database-id--', '--db-private-token--');
+$client = new Client('--my-database-id--', '--db-private-token--', ['region' => 'ap-se']);
 $client->send(new Reqs\ResetDatabase()); // Clear everything from the database
 
 /*

diff --git a/src/RecommApi/Client.php b/src/RecommApi/Client.php
@@ -24,11 +24,6 @@ class Client{
     protected $options;
     protected $guzzle_client;
 
-    /**
-     * @ignore
-     */
-    const BASE_URI = 'rapi.recombee.com';
-
     /**
      * @ignore
      */
@@ -38,27 +33,54 @@ class Client{
      * Create the client
      * @param string $account Name of your account at Recombee
      * @param string $token Secret token
-     * @param string $protocol Default protocol for sending requests. Possible values: 'http', 'https'.
      * @param array  $options Other custom options
      */
-    public function __construct($account, $token, $protocol = 'https', $options= array()) {
+    public function __construct($account, $token, $options = array()) {
         $this->account = $account;
         $this->token = $token;
-        $this->protocol = $protocol;
-        $this->base_uri = Client::BASE_URI;
+
+        if (!is_array($options)) throw new \InvalidArgumentException("options must be given as an array. $options given instead.");
         $this->options = $options;
 
-        if(getenv('RAPI_URI') !== false)
-            $this->base_uri = getenv('RAPI_URI');
-        else if (isset($this->options['baseUri']))
-            $this->base_uri = $this->options['baseUri'];
+        $this->protocol = (isset($this->options['protocol'])) ? $this->options['protocol'] : 'https';
+        $this->base_uri = $this->getBaseUri();
         $this->user_agent = $this->getUserAgent();
 
         $this->guzzle_client = new \GuzzleHttp\Client();
     }
 
+    protected function getRegionalBaseUri($region) {
+        $uriPerRegion = [
+            'ap-se' => 'rapi-ap-se.recombee.com',
+            'ca-east' => 'rapi-ca-east.recombee.com',
+            'eu-west' => 'rapi-eu-west.recombee.com',
+            'us-west' => 'rapi-us-west.recombee.com'
+          ];
+        $uri = $uriPerRegion[strtolower(strval($region))];
+        if (!isset($uri)) {
+            throw new \InvalidArgumentException("Region $region is unknown. You may need to update the version of the SDK.");
+        }
+        return $uri;
+    }
+
+    protected function getBaseUri() {
+        $base_uri = null;
+        if(getenv('RAPI_URI') !== false)
+            $base_uri = getenv('RAPI_URI');
+        else if (isset($this->options['baseUri']))
+            $base_uri = $this->options['baseUri'];
+
+        if (isset($this->options['region'])) {
+            if (isset($base_uri)) {
+                throw new \InvalidArgumentException('baseUri and region cannot be specified at the same time');
+            }
+            $base_uri = $this->getRegionalBaseUri($this->options['region']);
+        }
+        return (isset($base_uri)) ? $base_uri : 'rapi.recombee.com';
+    }
+
     protected function getUserAgent() {
-        $user_agent = 'recombee-php-api-client/3.2.0';
+        $user_agent = 'recombee-php-api-client/4.0.0';
         if (isset($this->options['serviceName']))
             $user_agent .= ' '.($this->options['serviceName']);
         return $user_agent;
@@ -84,6 +106,7 @@ public function send(Requests\Request $request) {
         $uri = $protocol . '://' . $this->base_uri . $signed_url;
         $timeout = $request->getTimeout() / 1000;
         $result = null;
+        $json = json_encode($request->getBodyParameters(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
 
         try {
             switch ($request->getMethod()) {
@@ -92,16 +115,14 @@ public function send(Requests\Request $request) {
                     break;
 
                 case Requests\Request::HTTP_PUT:
-                    $json = json_encode($request->getBodyParameters(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
                     $result = $this->put($uri, $timeout, $json);
                     break;
 
                 case Requests\Request::HTTP_DELETE:
-                    $result = $this->delete($uri, $timeout);
+                    $result = $this->delete($uri, $timeout, $json);
                     break;
 
                 case Requests\Request::HTTP_POST:
-                    $json = json_encode($request->getBodyParameters(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
                     $result = $this->post($uri, $timeout, $json);
                     break;
             }
@@ -145,7 +166,7 @@ protected function put($uri, $timeout, $body) {
         $headers = array_merge(array('Content-Type' => 'application/json'), $this->getHttpHeaders());
         $response = $this->guzzle_client->request('PUT', $uri, array_merge($options, ['body' => $body, 'headers' => $headers]));
         $this->checkErrors($response);
-        return (string) $response->getBody();
+        return $this->formatResult($response);
     }
 
     protected function get($uri, $timeout) {
@@ -154,16 +175,16 @@ protected function get($uri, $timeout) {
 
         $response = $this->guzzle_client->request('GET', $uri, array_merge($options, ['headers' => $headers]));
         $this->checkErrors($response);
-        return json_decode($response->getBody(), true);
+        return $this->formatResult($response);
     }
 
-    protected function delete($uri, $timeout) {
+    protected function delete($uri, $timeout, $body) {
         $options = array_merge(array('timeout' => $timeout), $this->getRequestOptions());
-        $headers = $this->getHttpHeaders();
+        $headers = array_merge(array('Content-Type' => 'application/json'), $this->getHttpHeaders());
 
-        $response = $this->guzzle_client->request('DELETE', $uri, array_merge($options, ['headers' => $headers]));
+        $response = $this->guzzle_client->request('DELETE', $uri, array_merge($options, ['body' => $body, 'headers' => $headers]));
         $this->checkErrors($response);
-        return (string) $response->getBody();
+        return $this->formatResult($response);
     }
 
     protected function post($uri, $timeout, $body) {
@@ -172,7 +193,10 @@ protected function post($uri, $timeout, $body) {
 
         $response = $this->guzzle_client->request('POST', $uri, array_merge($options, ['body' => $body, 'headers' => $headers]));
         $this->checkErrors($response);
+        return $this->formatResult($response);
+    }
 
+    protected function formatResult($response) {
         $json = json_decode($response->getBody(), true);
         if($json !== null && json_last_error() == JSON_ERROR_NONE)
             return $json;

diff --git a/src/RecommApi/Exceptions/UnknownOptionalParameterException.php b/src/RecommApi/Exceptions/UnknownOptionalParameterException.php
@@ -13,9 +13,9 @@
  */
 class UnknownOptionalParameterException extends \InvalidArgumentException {
 
-	/**
-	 * @var string $parameter Given invalid name
-	 */
+    /**
+     * @var string $parameter Given invalid name
+     */
     public $parameter;
 
     public function __construct($par, \Exception $previous = null) {

diff --git a/src/RecommApi/Requests/DeleteItem.php b/src/RecommApi/Requests/DeleteItem.php
@@ -12,7 +12,7 @@
 /**
  * Deletes an item of given `itemId` from the catalog.
  * If there are any *purchases*, *ratings*, *bookmarks*, *cart additions* or *detail views* of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some *series*, it will be removed from all the *series* where present.
- * If an item becomes obsolete/no longer available, it is often meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and only exclude the item from recommendations. In such a case, use [ReQL filter](https://docs.recombee.com/reql.html) instead of deleting the item completely.
+ * If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql.html) instead of deleting the item completely.
  */
 class DeleteItem extends Request {
 

diff --git a/src/RecommApi/Requests/DeleteMoreItems.php b/src/RecommApi/Requests/DeleteMoreItems.php
@@ -0,0 +1,69 @@
+<?php
+/*
+ This file is auto-generated, do not edit
+*/
+
+/**
+ * DeleteMoreItems request
+ */
+namespace Recombee\RecommApi\Requests;
+use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
+
+/**
+ * Delete all the items that pass the filter.
+ * If an item becomes obsolete/no longer available, it is meaningful to **keep it in the catalog** (along with all the interaction data, which are very useful), and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql.html) instead of deleting the item completely.
+ */
+class DeleteMoreItems extends Request {
+
+    /**
+     * @var string $filter A [ReQL](https://docs.recombee.com/reql.html) expression, which return `true` for the items that shall be updated.
+     */
+    protected $filter;
+
+    /**
+     * Construct the request
+     * @param string $filter A [ReQL](https://docs.recombee.com/reql.html) expression, which return `true` for the items that shall be updated.
+     */
+    public function __construct($filter) {
+        $this->filter = $filter;
+        $this->timeout = 1000;
+        $this->ensure_https = false;
+    }
+
+    /**
+     * Get used HTTP method
+     * @return static Used HTTP method
+     */
+    public function getMethod() {
+        return Request::HTTP_DELETE;
+    }
+
+    /**
+     * Get URI to the endpoint
+     * @return string URI to the endpoint
+     */
+    public function getPath() {
+        return "/{databaseId}/more-items/";
+    }
+
+    /**
+     * Get query parameters
+     * @return array Values of query parameters (name of parameter => value of the parameter)
+     */
+    public function getQueryParameters() {
+        $params = array();
+        return $params;
+    }
+
+    /**
+     * Get body parameters
+     * @return array Values of body parameters (name of parameter => value of the parameter)
+     */
+    public function getBodyParameters() {
+        $p = array();
+        $p['filter'] = $this->filter;
+        return $p;
+    }
+
+}
+?>
diff --git a/src/RecommApi/Requests/DeleteUser.php b/src/RecommApi/Requests/DeleteUser.php
@@ -16,13 +16,13 @@
 class DeleteUser extends Request {
 
     /**
-     * @var string $user_id ID of the user to be added.
+     * @var string $user_id ID of the user to be deleted.
      */
     protected $user_id;
 
     /**
      * Construct the request
-     * @param string $user_id ID of the user to be added.
+     * @param string $user_id ID of the user to be deleted.
      */
     public function __construct($user_id) {
         $this->user_id = $user_id;