README

简介。

Larcombee是Laravel的Recombee API包，它提供了一个简单的API实现，根据用户的行为和兴趣获取推荐。无论您使用Laravel构建什么，无论是电子商务、音乐市场还是电影平台，推荐系统都是必不可少的，这样您可以确保用户会在您的平台上花费更多时间。

什么是Recombee？

一个由数据科学家量身定制的RESTful API和SDK的人工智能推荐系统服务。

想了解更多关于它的工作原理？请查看以下链接。

入门。

安装Laracombee

composer require amranidev/laracombee

将服务提供者和别名添加到config/app.php

// Service provider.
Amranidev\Laracombee\Providers\LaracombeeServiceProvider::class,

// Alias.
'Laracombee' => Amranidev\Laracombee\Facades\LaracombeeFacade::class,

在recombee.com创建一个新实例
将databaseId和token添加到项目中的config/laracombee.php

恭喜，您已成功安装Laracombee！

用法。

使用Laracombe，数据集成非常简单。如您所知，Recombee使用基于用户-物品的数据库来根据用户的兴趣和交互来预测推荐。因此，您必须指定您希望用作用户以及物品的Laravel eloquent模型。

转到App\User，并添加您想要迁移到Recombee db的$laracombee，并为item做同样的事情。

注意：$laracombee属性必须是静态的。

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    public static $laracombee = ['name' => 'string', 'age' => 'int'];
}

配置。

首先，在laracombee.php配置文件中定义您的默认User和Item类。

    /*
    |--------------------------------------------------------------------------
    | Default models for user and item.
    |--------------------------------------------------------------------------
    |
    | Here where you can define the default class for user and item.
    |
    */

    'user'  => app(\App\User::class),
    'item'  => app(\App\Book::class),

当您触发laracombee artisan命令时，它将自动使用这些类作为参考。

其他配置选项。

您可以通过定义您想使用的http protocol来定义，默认是http
您可以通过定义每个请求的默认timeout（毫秒）来定义。默认是2000

命令。

Larcombe提供了一系列artisan命令，为您提供了流畅的工作流程，例如迁移、回滚、播种、添加列和删除列。

迁移和回滚命令。

如您所记得，每次您触发迁移或回滚命令时，Laracombee都会查找$laracombee属性并准备模式。您只需指定您想要迁移/回滚的目录（用户/物品）并提供建模命名空间，Laracombee就会为您完成工作。

迁移 user : php artisan laracombee:migrate user

迁移 item : php artisan laracombee:migrate item

回滚 user : php artisan laracombee:rollback user

回滚 item : php artisan laracombee:rollback item

播种命令。

如果您想将数据库中已经存在的用户或物品记录索引到Recombee中，可以运行播种命令。

注意：运行此命令可能需要几分钟，具体取决于您的记录。

索引 user : php artisan laracombee:seed user

索引 item : php artisan laracombee:seed item

添加/删除列。

您可以使用以下命令添加或删除列

添加列 : php artisan laracombee:add email:string age:integer --to=user

删除列 : php artisan laracombee:drop email age --from=user

重置命令。

php artisan laracombee:reset

此命令将完全删除所有您的数据，包括项目、项目属性、系列、用户数据库、购买记录、评分、详细视图和书签。请确保在生产环境中永远不要执行此请求！重置数据库是不可逆的，⚠️ 在运行此命令之前请三思⚠️

Laracombee 魔法方法。

该包允许通过魔法方法管理 recombee 用户/项目。

示例。

// Add a user to recombee.

$user = User::findOrFail($id);

$addUser = Laracombee::addUser($user);

Laracombee::send($addUser)->then(function () {
  // Success.
})->otherWise(function ($error) {
  // Handle Exeption.
})->wait();

如您所见，我们使用了名为 addUser 的魔法方法，它返回 \Recombee\RecommApi\Requests\Request，然后我们触发了 send 方法以将用户保存到 recombee 数据库中，让我简单介绍一下 send 方法。

此方法负责向 Recombee 服务器发送请求，每次您想要您的应用程序与 Recombee 交互时，您可能需要触发此方法，添加新用户、添加项目，甚至删除它。

send 方法总是返回一个承诺，这使得您能够轻松地管理来自服务器的响应。

您还可以将多个用户批量添加到 Recombee 数据库中。如果您想这样做，可以使用 addUsers 魔法方法，并通过参数传递一个用户数组，然后您必须触发 batch 方法来发送请求，使用 batch 在同时发送多个请求时可能更好。

// Get users from your db.
$user1 = User::findOrFail(1);
$user2 = User::findOrFail(2);
$user3 = User::findOrFail(3);

// Prepare request.
$users = Laracombee::addUsers([$user1, $user2, $user3]);

// Send request as bulk.
Laracombee::batch($users);

您还可以向用户推荐项目。

$user = User::findOrFail($id);

// Prepare the request for recombee server, we need 10 recommended items for a given user.
$recommendations = Laracombee::recommendTo($user, 1O)->wait();

注意：与 API 的其余部分不同，推荐 API 会自动触发 send 方法，因此无需调用 send 方法。

推荐 API 返回包含名为 recomms 的推荐（项目 ID）数组的数组响应。

$itemsIds = $recommendations['recomms']; // [2, 5, 55, 24, 32, 91]

$items = \App\Item::find($itemsIds);

其他魔法方法。

更新用户，Laracombee::updateUser($user);

合并用户，Laracombee::mergeUsers($user1, $user2);

添加项目，Laracombee::addItem($item);

更新项目，Laracombee::updateItem($item);

添加多个项目，Laracombee::addItems($items);

API。

Laracombee 遵循与 recombee 相同的命名约定，请参阅 recombee API 文档。

用户。

从数据库中删除指定 userId 的用户，Laracombee::deleteUser($user_id);
合并两个用户，Laracombee::mergeUsersWithId($source_user_id, $target_user_id);

将两个不同用户的交互（购买、评分、书签、详细视图等）合并到单个用户 ID 下。这在处理匿名用户（例如通过会话 ID 标识）的在线电子商务应用程序中特别有用。在这样的应用程序中，用户可能拥有持久账户，但在将项目放入购物车时匿名访问系统。在某个时候，例如当用户希望确认购买时，他们会使用他们的用户名和密码登录系统。在匿名会话 ID 下进行的交互随后将与持久账户连接起来，合并这两个账户变得很有吸引力。

合并发生在两个称为目标用户和源用户的用户之间。合并后，源用户的所有交互都归因于目标用户，源用户被删除。

获取当前目录中用户 ID 的列表，Laracombee::listUsers($options);。
添加用户属性类似于向用户表添加列。用户可能由各种类型的各种属性来表征，Laracombee::addUserProperty($property, $type);。
删除用户属性大致相当于从用户表中删除列，Laracombee::deleteUserProperty($property);。
设置/更新给定用户的（一些）属性值。属性（列）必须由添加用户属性预先创建，Laracombee::setUserValues($user_id, $fields);。
获取给定用户的所有当前属性值，Laracombee::getUserValues($user_id);。

物品。

添加一个物品属性相当于在物品表中添加一列。物品可能具有各种不同类型的属性，Laracombee::addItemProperty($property, $type);
删除一个物品属性相当于从物品表中删除一列，Laracombee::deleteItemProperty($property);
设置/更新指定物品的（某些）属性值。属性（列）必须先通过添加物品属性创建，Laracombee::setItemValues($item_id, $fields);
获取指定物品的所有当前属性值，Laracombee::getItemValues($item_id);
从目录中删除给定itemId的物品，Laracombee::deleteItem($item_id);

用户-物品交互。

以下方法允许添加、删除和列出用户与物品之间的交互。

详细视图

添加由指定用户创建的给定物品的详细视图，Laracombee::addDetailView($user_id, $item_id, $options);
删除通过（userId, itemId, 和时间戳）唯一指定的现有详细视图或如果省略时间戳，则删除给定userId和itemId的所有详细视图，Laracombee::deleteDetailView($user_id, $item_id, $options);
列出由不同用户创建的给定物品的所有详细视图，Laracombee::listItemDetailViews($item_id);
列出由指定用户创建的给定物品的所有详细视图，Laracombee::listUserDetailViews($user_id);

购买

添加由指定用户进行的给定物品的购买，Laracombee::addPurchase($user_id, $item_id, $options);
删除通过userId, itemId, 和时间戳唯一指定的现有购买或如果省略时间戳，则删除给定userId和itemId的所有购买，Laracombee::deletePurchase($user_id, $item_id, $options);

评分

添加由指定用户对给定物品的评分，Laracombee::addRating($user_id, $iten_id, $options);
从数据库中删除通过（userId, itemId, 时间戳）指定的现有评分或如果省略时间戳，则删除给定userId和itemId的所有评分，Laracombee::deleteRating($user_id, $item_id, $options);

购物车添加

添加由指定用户进行的给定物品的购物车添加，Laracombee::addCartAddition($user_id, $item_id, $options);
删除通过userId, itemId, 和时间戳唯一指定的现有购物车添加或如果省略时间戳，则删除给定userId和itemId的所有购物车添加，Laracombee::deleteCartAddition($user_id, $item_id, $options);

书签

添加由指定用户对给定物品的书签，Laracombee::addBookmark($user_id, $item_id, $options);
删除通过userId, itemId, 和时间戳唯一指定的书签或如果省略时间戳，则删除给定userId和itemId的所有书签，Laracombee::deleteBookmark($user_id, $item_id, $options);

检索推荐

推荐方法能够推荐物品（向用户推荐物品，向用户推荐用户）。

根据用户过去与物品的交互（购买、评分等），为给定用户推荐最有可能是高价值的top-N物品，Laracombee::recommendItemsToUser($user_id, $limit, $options);
根据用户的过去交互（购买、评分等）和属性值，获取与某些给定用户相似的用户，Laracombee::recommendUsersToUser($user_id, $limit, $options);

定制您的魔法方法。

有时，我们需要保持代码的一致性，因此我们希望可以扩展已安装包的功能，并适应我们的需求。

您可以按自己的喜好定制API，您可以通过扩展AbstractRecombee类并实现send抽象方法来实现这一点，然后您就可以开始了。

示例

假设您不喜欢Laracombee处理recombee请求/响应的方式，处理异常的方式也不符合您的要求，并且您需要一个可以将用户设置为recombee数据库中的顶级卖家的方法。

让我们创建一个新的类，您可以选择将其注册为一个外观（如果您愿意的话）。

<?php

namespace Acme\Myrecombee;

use Recombee\RecommApi\Requests\Request;
use Amranidev\Laracombee\AbstractRecombee;

class MyRecombee extends AbstractRecombee
{
    public function __construct()
    {
        parent::__construct(config('laracombee.database'), config('laracombee.token'), config('laracombee.protocol'));
    }
    
    /**
     * @param \App\User $user
     */
    public function setTopSeller(User $user)
    {
        // Note that we assume that 'isTopSeller' column is already exists in the db. 
        return $this->setUserValues($user->id, ['isTopSeller' => true]);
    }
    
     /**
      * Send request.
      *
      * @param \Recombee\RecommApi\Requests\Request $request
      *
      * @return mixed
      */
     public function send(Request $request)
     {       
         try {
             $response = $this->client->send($request);
         } catch (Exceptions\ApiTimeoutException $e) {
              // Deal with Api exception
         } catch (Exceptions\ResponseException $e) {
              // Deal with Response exception
         } catch (Exceptions\ApiException $e) {
              // Deal with Api exception
         }

         return $response;
     }
}

然后您可以在您的项目中使用这些功能。

$user = User::findorfail($id);

$request = MyRecombee::setTopSeller($user);

$response = MyRecombee::send($request);

使用多个recombee数据库。

Laracombee让您能够使用多个recombee数据库，让您能够创建一个自定义类，用于与其他recombee实例交互。

您可以使用php artisan laracombee:new <ClassName>创建一个新的Laracombee类，它将在app/Laracombee目录中创建一个新的Laracombee类。

贡献

感谢您考虑为这个项目做出贡献！贡献指南可以在贡献指南中找到。

您可以随时报告任何错误，提交任何功能请求，甚至提出任何问题。

待办事项

将剩余的API添加到larcombe，检查recombee的api文档。

amranidev / laracombee

维护者

详细信息