Skip to content

Commit 800d3fc

Browse files
OndraFiedlerOndraFiedler
committed
PHP client for Recombee API
0 parents  commit 800d3fc

File tree

125 files changed

+5913
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

125 files changed

+5913
-0
lines changed

‎LICENSE.txt

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2015 Recombee s.r.o.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Recombee API Client
2+
3+
A PHP client for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
4+
5+
Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
6+
7+
## Installation
8+
9+
The best way to install the client is through dependency manager [Composer](https://getcomposer.org/):
10+
11+
```
12+
composer require recombee/php-api-client
13+
```
14+
or
15+
```
16+
{
17+
"require": {
18+
"recombee/php-api-client": ">=0.1"
19+
}
20+
}
21+
```
22+
23+
## Examples
24+
25+
### Basic example
26+
```php
27+
use Recombee\RecommApi\Client;
28+
use Recombee\RecommApi\Requests as Reqs;
29+
use Recombee\RecommApi\Exceptions as Ex;
30+
31+
const NUM = 100;
32+
const PROBABILITY_PURCHASED = 0.01;
33+
34+
// Prepare some users and items
35+
$my_user_ids = array();
36+
$my_item_ids = array();
37+
for($i=0; $i < NUM; $i++) {
38+
array_push($my_user_ids, "user-{$i}");
39+
array_push($my_item_ids, "item-{$i}");
40+
}
41+
42+
// Generate some random purchases of items by users
43+
$my_purchases = array();
44+
foreach ($my_user_ids as $user_id) {
45+
foreach ($my_item_ids as $item_id) {
46+
if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED)
47+
array_push($my_purchases, ['user'=>$user_id, 'item'=>$item_id]);
48+
}
49+
}
50+
51+
// Use Recombee recommender
52+
$client = new Client('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L');
53+
54+
try
55+
{
56+
$client->send(new Reqs\ResetDatabase()); //Clear everything from the database
57+
58+
//Create requests and send the data to Recombee, use Batch for faster processing
59+
echo "Send users\n";
60+
$user_requests = array_map(function($userId) {return new Reqs\AddUser($userId);}, $my_user_ids);
61+
$client->send(new Reqs\Batch($user_requests));
62+
63+
echo "Send items\n";
64+
$item_requests = array_map(function($itemId) {return new Reqs\AddItem($itemId);}, $my_item_ids);
65+
$client->send(new Reqs\Batch($item_requests));
66+
67+
echo "Send purchases\n";
68+
$purchase_requests = array_map(function($tuple)
69+
{return new Reqs\AddPurchase($tuple['user'], $tuple['item'], time());}, $my_purchases);
70+
$client->send(new Reqs\Batch($purchase_requests));
71+
72+
// Get 5 recommendations for user 'user-25'
73+
$recommended = $client->send(new Reqs\UserBasedRecommendation('user-25', 5, ['rotationRate' => 0]));
74+
echo 'Recommended items: ' . implode(',',$recommended) . "\n";
75+
}
76+
catch(Ex\ApiTimeoutException $e)
77+
{
78+
//use fallback
79+
}
80+
```
81+
82+
### Using property values
83+
```php
84+
use Recombee\RecommApi\Client;
85+
use Recombee\RecommApi\Requests as Reqs;
86+
use Recombee\RecommApi\Exceptions as Ex;
87+
88+
const NUM = 100;
89+
const PROBABILITY_PURCHASED = 0.1;
90+
91+
$client = new Client('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L');
92+
$client->send(new Reqs\ResetDatabase()); //Clear everything from the database
93+
94+
/*
95+
We will use computers as items in this example
96+
Computers have three properties
97+
- price (floating point number)
98+
- number of processor cores (integer number)
99+
- description (string)
100+
*/
101+
102+
// Add properties of items
103+
$client->send(new Reqs\AddItemProperty('price', 'double'));
104+
$client->send(new Reqs\AddItemProperty('num-cores', 'int'));
105+
$client->send(new Reqs\AddItemProperty('description', 'string'));
106+
107+
# Prepare requests for setting a catalog of computers
108+
$requests = array();
109+
for($i=0; $i<NUM; $i++)
110+
{
111+
$r = new Reqs\SetItemValues(
112+
"computer-{$i}", //itemId
113+
//values:
114+
[
115+
'price' => rand(15000, 25000),
116+
'num-cores' => rand(1, 8),
117+
'description' => 'Great computer',
118+
'!cascadeCreate' => true // Use !cascadeCreate for creating item
119+
// with given itemId, if it doesn't exist
120+
]
121+
);
122+
array_push($requests, $r);
123+
}
124+
125+
// Send catalog to the recommender system
126+
$client->send(new Reqs\Batch($requests));
127+
128+
// Generate some random purchases of items by users
129+
$requests = array();
130+
131+
for($i=0; $i<NUM; $i++)
132+
for($j=0; $j<NUM; $j++)
133+
if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED)
134+
{
135+
$r = new Reqs\AddPurchase("user-{$i}", "computer-{$j}", time(), ['cascadeCreate' => true]);
136+
array_push($requests, $r);
137+
}
138+
139+
// Send purchases to the recommender system
140+
$client->send(new Reqs\Batch($requests));
141+
142+
// Get 5 recommendations for user-42, who is currently viewing computer-6
143+
$recommended = $client->send(new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42']));
144+
echo 'Recommended items: ' . implode(',',$recommended) . "\n";
145+
146+
// Get 5 recommendations for user-42, but recommend only computers that
147+
// have at least 3 cores
148+
$recommended = $client->send(
149+
new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42', 'filter' => "'num-cores'>=3"])
150+
);
151+
echo 'Recommended items with at least 3 processor cores: ' . implode(',',$recommended) . "\n";
152+
153+
// Get 5 recommendations for user-42, but recommend only items that
154+
// are more expensive then currently viewed item (up-sell)
155+
$recommended = $client->send(
156+
new Reqs\ItemBasedRecommendation('computer-6', 5,
157+
['targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"])
158+
);
159+
echo 'Recommended up-sell items: ' . implode(',',$recommended) . "\n"
160+
```
161+
162+
### Exception handling
163+
164+
For the sake of brevity, the above examples omit exception handling. However, various exceptions can occur while processing request, for example because of adding an already existing item, submitting interaction of nonexistent user or because of timeout.
165+
166+
We are doing our best to provide the fastest and most reliable service, but production-level applications must implement a fallback solution since errors can always happen. The fallback might be, for example, showing the most popular items from the current category, or not displaying recommendations at all.
167+
168+
Example:
169+
```php
170+
use Recombee\RecommApi\Client;
171+
use Recombee\RecommApi\Requests as Reqs;
172+
use Recombee\RecommApi\Exceptions as Ex;
173+
174+
try
175+
{
176+
$recommended = $client->send(
177+
new Reqs\ItemBasedRecommendation('computer-6', 5,
178+
['targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"])
179+
);
180+
}
181+
catch(Ex\ApiTimeoutException $e)
182+
{
183+
//Handle timeout => use fallback
184+
}
185+
catch(Ex\ResponseException $e)
186+
{
187+
//Handle errorneous request => use fallback
188+
}
189+
catch(Ex\ApiException $e)
190+
{
191+
//ApiException is parent of both ResponseException and ApiTimeoutException
192+
}
193+
```

‎composer.json

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"name": "recombee/php-api-client",
3+
"description": "PHP client for easy use of the Recombee recommendation API.",
4+
"homepage": "https://recombee.com",
5+
"license": "MIT",
6+
"authors": [
7+
{
8+
"name": "Ondřej Fiedler",
9+
"email": "[email protected]"
10+
}
11+
],
12+
"require": {
13+
"php": ">=5.4.0",
14+
"rmccue/requests": ">=1.0"
15+
},
16+
"require-dev": {
17+
"phpunit/phpunit": ">=4",
18+
"phpdocumentor/phpdocumentor": "2.*"
19+
},
20+
"autoload": {
21+
"psr-4": {
22+
"Recombee\\": "src/",
23+
"Recombee\\RecommApi\\Tests\\": "tests/"
24+
}
25+
}
26+
}

‎phpdoc.dist.xml

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<phpdoc>
3+
<title>Recombee API client</title>
4+
<transformations>
5+
<template name="responsive-twig"/>
6+
</transformations>
7+
<parser>
8+
<target>doc</target>
9+
</parser>
10+
<transformer>
11+
<target>doc</target>
12+
</transformer>
13+
<files>
14+
<directory>src</directory>
15+
</files>
16+
</phpdoc>

0 commit comments

Comments
 (0)