Skip to content

Commit 430edd7

Browse files
OndraFiedlerOndraFiedler
committed
Support returnProperties and includedProperties parameters of recommendation requests
1 parent 037df8a commit 430edd7

32 files changed

Lines changed: 613 additions & 512 deletions

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
A PHP client for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
44

5+
If you don't have an account at Recombee yet, you can create a free account [here](https://www.recombee.com/).
6+
57
Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
68

79
## Installation

‎src/RecommApi/Client.php‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ class Client{
2020
protected $token;
2121
protected $request;
2222
protected $protocol;
23+
protected $base_uri;
2324

2425
/**
2526
* @ignore
@@ -36,6 +37,9 @@ public function __construct($account, $token, $protocol = 'http') {
3637
$this->account = $account;
3738
$this->token = $token;
3839
$this->protocol = $protocol;
40+
$this->base_uri = Client::BASE_URI;
41+
if(getenv("RAPI_URI") !== false)
42+
$this->base_uri = getenv("RAPI_URI");
3943
}
4044

4145
/**
@@ -47,10 +51,10 @@ public function __construct($account, $token, $protocol = 'http') {
4751
public function send(Requests\Request $request) {
4852
$this->request = $request;
4953
$path = Util::sliceDbName($request->getPath());
50-
$request_url = $path . $this->paramsToStr($request->getQueryParameters());
54+
$request_url = $path . $this->paramsToUrl($request->getQueryParameters());
5155
$signed_url = $this->signUrl($request_url);
5256
$protocol = ($request->getEnsureHttps()) ? 'https' : $this->protocol;
53-
$uri = $protocol . '://' . Client::BASE_URI . $signed_url;
57+
$uri = $protocol . '://' . $this->base_uri . $signed_url;
5458
$timeout = $request->getTimeout() / 1000;
5559
$result = null;
5660

@@ -144,15 +148,22 @@ protected function hmacSign($uri, $timeStr) {
144148

145149
/* ----------------------- Util ----------------------- */
146150

147-
protected function paramsToStr($params) {
151+
protected function paramsToUrl($params) {
148152
if (!$params) return '';
149153

150154
$urlp = array();
151155
foreach ($params as $p => $val) {
152-
array_push($urlp, urlencode($p) . '=' . urlencode($val));
156+
array_push($urlp, urlencode($p) . '=' . urlencode($this->formatQueryParameterValue($val)));
153157
}
154158
$result = '?' . implode ('&' , $urlp);
155159
return $result;
156160
}
161+
162+
protected function formatQueryParameterValue($value) {
163+
if (is_array($value))
164+
return implode(',', $value);
165+
else return $value;
166+
}
167+
157168
}
158169
?>

‎src/RecommApi/Requests/DeleteBookmark.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp`.
13+
* Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp` or all the bookmarks with given `userId` and `itemId` if `timestamp` is omitted.
1414
*/
1515
class DeleteBookmark extends Request {
1616

‎src/RecommApi/Requests/DeleteCartAddition.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Deletes an existing cart addition uniquely specified by `userId`, `itemId`, and `timestamp`.
13+
* Deletes an existing cart addition uniquely specified by `userId`, `itemId`, and `timestamp` or all the cart additions with given `userId` and `itemId` if `timestamp` is omitted.
1414
*/
1515
class DeleteCartAddition extends Request {
1616

‎src/RecommApi/Requests/DeleteDetailView.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Deletes an existing detail view uniquely specified by (`userId`, `itemId`, and `timestamp`).
13+
* Deletes an existing detail view uniquely specified by (`userId`, `itemId`, and `timestamp`) or all the detail views with given `userId` and `itemId` if `timestamp` is omitted.
1414
*/
1515
class DeleteDetailView extends Request {
1616

‎src/RecommApi/Requests/DeletePurchase.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Deletes an existing purchase uniquely specified by `userId`, `itemId`, and `timestamp`.
13+
* Deletes an existing purchase uniquely specified by `userId`, `itemId`, and `timestamp` or all the purchases with given `userId` and `itemId` if `timestamp` is omitted.
1414
*/
1515
class DeletePurchase extends Request {
1616

‎src/RecommApi/Requests/DeleteRating.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Deletes an existing rating specified by (`userId`, `itemId`, `timestamp`) from the database.
13+
* Deletes an existing rating specified by (`userId`, `itemId`, `timestamp`) from the database or all the ratings with given `userId` and `itemId` if `timestamp` is omitted.
1414
*/
1515
class DeleteRating extends Request {
1616

‎src/RecommApi/Requests/ItemBasedRecommendation.php‎

Lines changed: 91 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,48 @@ class ItemBasedRecommendation extends Request {
5050
* @var string $scenario Scenario defines a particular application of recommendations. It can be for example "homepage" or "cart". The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
5151
*/
5252
protected $scenario;
53+
/**
54+
* @var bool $return_properties With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.
55+
* Example response:
56+
* ```
57+
* [
58+
* {
59+
* "itemId": "tv-178",
60+
* "description": "4K TV with 3D feature",
61+
* "categories": ["Electronics", "Televisions"],
62+
* "price": 342,
63+
* "url": "myshop.com/tv-178"
64+
* },
65+
* {
66+
* "itemId": "mixer-42",
67+
* "description": "Stainless Steel Mixer",
68+
* "categories": ["Home & Kitchen"],
69+
* "price": 39,
70+
* "url": "myshop.com/mixer-42"
71+
* }
72+
* ]
73+
* ```
74+
*/
75+
protected $return_properties;
76+
/**
77+
* @var string $included_properties Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
78+
* Example response for `includedProperties=description,price`:
79+
* ```
80+
* [
81+
* {
82+
* "itemId": "tv-178",
83+
* "description": "4K TV with 3D feature",
84+
* "price": 342
85+
* },
86+
* {
87+
* "itemId": "mixer-42",
88+
* "description": "Stainless Steel Mixer",
89+
* "price": 39
90+
* }
91+
* ]
92+
* ```
93+
*/
94+
protected $included_properties;
5395
/**
5496
* @var float $diversity **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
5597
*/
@@ -63,7 +105,7 @@ class ItemBasedRecommendation extends Request {
63105
*/
64106
protected $rotation_rate;
65107
/**
66-
* @var float $rotation_time **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour. |
108+
* @var float $rotation_time **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
67109
*/
68110
protected $rotation_time;
69111
/**
@@ -98,6 +140,46 @@ class ItemBasedRecommendation extends Request {
98140
* - *scenario*
99141
* - Type: string
100142
* - Description: Scenario defines a particular application of recommendations. It can be for example "homepage" or "cart". The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
143+
* - *returnProperties*
144+
* - Type: bool
145+
* - Description: With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.
146+
* Example response:
147+
* ```
148+
* [
149+
* {
150+
* "itemId": "tv-178",
151+
* "description": "4K TV with 3D feature",
152+
* "categories": ["Electronics", "Televisions"],
153+
* "price": 342,
154+
* "url": "myshop.com/tv-178"
155+
* },
156+
* {
157+
* "itemId": "mixer-42",
158+
* "description": "Stainless Steel Mixer",
159+
* "categories": ["Home & Kitchen"],
160+
* "price": 39,
161+
* "url": "myshop.com/mixer-42"
162+
* }
163+
* ]
164+
* ```
165+
* - *includedProperties*
166+
* - Type: string
167+
* - Description: Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
168+
* Example response for `includedProperties=description,price`:
169+
* ```
170+
* [
171+
* {
172+
* "itemId": "tv-178",
173+
* "description": "4K TV with 3D feature",
174+
* "price": 342
175+
* },
176+
* {
177+
* "itemId": "mixer-42",
178+
* "description": "Stainless Steel Mixer",
179+
* "price": 39
180+
* }
181+
* ]
182+
* ```
101183
* - *diversity*
102184
* - Type: float
103185
* - Description: **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
@@ -109,7 +191,7 @@ class ItemBasedRecommendation extends Request {
109191
* - Description: **Expert option** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
110192
* - *rotationTime*
111193
* - Type: float
112-
* - Description: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour. |
194+
* - Description: **Expert option** Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. By example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
113195
* @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
114196
*/
115197
public function __construct($item_id, $count, $optional = array()) {
@@ -122,13 +204,15 @@ public function __construct($item_id, $count, $optional = array()) {
122204
$this->allow_nonexistent = isset($optional['allowNonexistent']) ? $optional['allowNonexistent'] : null;
123205
$this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
124206
$this->scenario = isset($optional['scenario']) ? $optional['scenario'] : null;
207+
$this->return_properties = isset($optional['returnProperties']) ? $optional['returnProperties'] : null;
208+
$this->included_properties = isset($optional['includedProperties']) ? $optional['includedProperties'] : null;
125209
$this->diversity = isset($optional['diversity']) ? $optional['diversity'] : null;
126210
$this->min_relevance = isset($optional['minRelevance']) ? $optional['minRelevance'] : null;
127211
$this->rotation_rate = isset($optional['rotationRate']) ? $optional['rotationRate'] : null;
128212
$this->rotation_time = isset($optional['rotationTime']) ? $optional['rotationTime'] : null;
129213
$this->optional = $optional;
130214

131-
$existing_optional = array('targetUserId','userImpact','filter','booster','allowNonexistent','cascadeCreate','scenario','diversity','minRelevance','rotationRate','rotationTime');
215+
$existing_optional = array('targetUserId','userImpact','filter','booster','allowNonexistent','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime');
132216
foreach ($this->optional as $key => $value) {
133217
if (!in_array($key, $existing_optional))
134218
throw new UnknownOptionalParameterException($key);
@@ -174,6 +258,10 @@ public function getQueryParameters() {
174258
$params['cascadeCreate'] = $this->optional['cascadeCreate'];
175259
if (isset($this->optional['scenario']))
176260
$params['scenario'] = $this->optional['scenario'];
261+
if (isset($this->optional['returnProperties']))
262+
$params['returnProperties'] = $this->optional['returnProperties'];
263+
if (isset($this->optional['includedProperties']))
264+
$params['includedProperties'] = $this->optional['includedProperties'];
177265
if (isset($this->optional['diversity']))
178266
$params['diversity'] = $this->optional['diversity'];
179267
if (isset($this->optional['minRelevance']))

‎src/RecommApi/Requests/ResetDatabase.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ class ResetDatabase extends Request {
1919
* Construct the request
2020
*/
2121
public function __construct() {
22-
$this->timeout = 5000;
22+
$this->timeout = 20000;
2323
$this->ensure_https = false;
2424
}
2525

‎src/RecommApi/Requests/SetItemValues.php‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
1111

1212
/**
13-
* Set/update (some) property values of a given item.
13+
* Set/update (some) property values of a given item. The properties (columns) must be previously created by [Add item property](https://docs.recombee.com/api.html#add-item-property).
1414
*/
1515
class SetItemValues extends Request {
1616

@@ -23,8 +23,9 @@ class SetItemValues extends Request {
2323
* Example of body:
2424
* ```
2525
* {
26-
* "string_property": "strvalue",
27-
* "integer_property": 42,
26+
* "product_description": "4K TV with 3D feature",
27+
* "categories": ["Electronics", "Televisions"],
28+
* "price_usd": 342,
2829
* "!cascadeCreate": true
2930
* }
3031
* ```
@@ -39,8 +40,9 @@ class SetItemValues extends Request {
3940
* Example of body:
4041
* ```
4142
* {
42-
* "string_property": "strvalue",
43-
* "integer_property": 42,
43+
* "product_description": "4K TV with 3D feature",
44+
* "categories": ["Electronics", "Televisions"],
45+
* "price_usd": 342,
4446
* "!cascadeCreate": true
4547
* }
4648
* ```

0 commit comments

Comments
 (0)