README

一个PHP客户端，方便使用Recombee推荐API。

如果您还没有Recombee账户，您可以在这里创建一个免费账户。

API文档可以在docs.recombee.com找到。

安装

最佳安装方式是通过依赖管理器Composer

composer require ivanapostic/php-api-client

或

{
    "require": {
        "ivanapostic/php-api-client": "^1.3.2"
    }
}

示例

基本示例

use Recombee\RecommApi\Client;
use Recombee\RecommApi\Requests as Reqs;
use Recombee\RecommApi\Exceptions as Ex;

$client = new Client('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L');

const NUM = 100;
const PROBABILITY_PURCHASED = 0.1;

try
{
    // Generate some random purchases of items by users
    $purchase_requests = array();
    for($i=0; $i < NUM; $i++) {
        for($j=0; $j < NUM; $j++) {
            if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED) {

                $request = new Reqs\AddPurchase("user-{$i}", "item-{$j}",
                    ['cascadeCreate' => true] // Use cascadeCreate to create the
                                              // yet non-existing users and items
                );
                array_push($purchase_requests, $request);
            }
        }
    }
    echo "Send purchases\n";
    $res = $client->send(new Reqs\Batch($purchase_requests)); //Use Batch for faster processing of larger data

    // Get 5 recommendations for user 'user-25'
    $recommended = $client->send(new Reqs\UserBasedRecommendation('user-25', 5));

    echo 'Recommended items: ' . implode(',',$recommended) . "\n";
}
catch(Ex\ApiException $e)
{
    //use fallback
}

使用属性值

use Recombee\RecommApi\Client;
use Recombee\RecommApi\Requests as Reqs;
use Recombee\RecommApi\Exceptions as Ex;

const NUM = 100;
const PROBABILITY_PURCHASED = 0.1;

$client = new Client('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L');
$client->send(new Reqs\ResetDatabase()); //Clear everything from the database

/*
We will use computers as items in this example
Computers have three properties 
  - price (floating point number)
  - number of processor cores (integer number)
  - description (string)
*/

// Add properties of items
$client->send(new Reqs\AddItemProperty('price', 'double'));
$client->send(new Reqs\AddItemProperty('num-cores', 'int'));
$client->send(new Reqs\AddItemProperty('description', 'string'));
$client->send(new Reqs\AddItemProperty('in_stock_from', 'timestamp'));

# Prepare requests for setting a catalog of computers
$requests = array();
for($i=0; $i<NUM; $i++)
{
    $r = new Reqs\SetItemValues(
      "computer-{$i}", //itemId
      //values:
      [ 
        'price' => rand(15000, 25000),
        'num-cores' => rand(1, 8),
        'description' => 'Great computer',
        'in_stock_from' => new DateTime('NOW')
      ],
      //optional parameters:
      ['cascadeCreate' => true] // Use cascadeCreate for creating item
                                 // with given itemId, if it doesn't exist]
    );
    array_push($requests, $r);
}

// Send catalog to the recommender system
$result =  $client->send(new Reqs\Batch($requests));
var_dump($result);

// Generate some random purchases of items by users
$requests = array();

for($i=0; $i<NUM; $i++)
    for($j=0; $j<NUM; $j++)
        if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED)
        {
           $r = new Reqs\AddPurchase("user-{$i}", "computer-{$j}", ['cascadeCreate' => true]);
           array_push($requests, $r);
        }

// Send purchases to the recommender system
$client->send(new Reqs\Batch($requests));

// Get 5 items related to item computer-6. Personalize them for user-42, who is currently viewing that item.
$recommended = $client->send(new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42']));
echo 'Recommended items: ' . implode(',',$recommended) . "\n";

// Recommend only computers that have at least 3 cores
$recommended = $client->send(
  new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42', 'filter' => "'num-cores'>=3"])
  );
echo 'Recommended items with at least 3 processor cores: ' . implode(',',$recommended) . "\n";

// Recommend only items that are more expensive then currently viewed item computer-6 (up-sell)
$recommended = $client->send(
  new Reqs\ItemBasedRecommendation('computer-6', 5,
    ['targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"])
  );
echo 'Recommended up-sell items: ' . implode(',',$recommended) . "\n"

异常处理

为了简洁，上述示例省略了异常处理。然而，在处理请求时可能会发生各种异常，例如由于添加已存在的项，提交不存在的用户的交互或因为超时而引起。

我们正在努力提供最快、最可靠的服务，但是生产级应用程序必须实现回退解决方案，因为错误总是可能发生的。例如，回退可能是显示当前类别的热门商品，或者完全不显示推荐。

示例

use Recombee\RecommApi\Client;
use Recombee\RecommApi\Requests as Reqs;
use Recombee\RecommApi\Exceptions as Ex;

try
{
    $recommended = $client->send(
      new Reqs\ItemBasedRecommendation('computer-6', 5,
        ['targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"])
    );
}
catch(Ex\ApiTimeoutException $e)
{
    //Handle timeout => use fallback
}
catch(Ex\ResponseException $e)
{
    //Handle errorneous request => use fallback
}
catch(Ex\ApiException $e)
{
    //ApiException is parent of both ResponseException and ApiTimeoutException
}