Download the PHP package amranidev/laracombee without Composer

Laracombee

Laracombee is a Laravel package for the Recombee recommendation API. It provides a simple Laravel-friendly interface for working with users, items, user-item interactions, and recommendations.

This package is useful for applications such as e-commerce platforms, media libraries, and marketplaces where personalized recommendations can improve engagement and retention.

What is Recombee?

Recombee is an AI-powered recommendation service with a REST API and SDKs for building personalized recommendation systems.

To learn more about how Recombee works, see the official documentation:

• Recombee API documentation

Requirements

• PHP 8.2 or later
• Laravel 10, 11, or 12

Installation

Install the package with Composer:

Laravel package discovery will register the service provider automatically.

If you want to publish the configuration file, run:

Then add your Recombee database ID and private token to config/laracombee.php.

Configuration

Set your default user and item models in config/laracombee.php:

These classes are used by the package commands.

You can also configure:

• protocol: the HTTP protocol used for requests. The default is http.
• timeout: the default request timeout in milliseconds. The default is 2000.
• region: the Recombee region. The default is eu-west.

Defining Recombee Properties

Each model that should be synchronized with Recombee must define a static $laracombee property.

Do the same for your item model.

Usage

Add a user

Add multiple users in a batch

Recommend items to a user

Unlike most other methods in the package, recommendation methods trigger the request immediately and return a promise directly.

Commands

Laracombee includes several Artisan commands for managing your Recombee schema and data.

Migrate properties

These commands read the static $laracombee property from the configured model and create the corresponding Recombee properties.

Roll back properties

Seed existing records

You can also set a custom chunk size:

Add or drop properties manually

Reset the Recombee database

This command permanently removes all Recombee data, including users, items, properties, ratings, detail views, purchases, bookmarks, and series data. Do not run it in production unless you explicitly intend to wipe the Recombee database.

Generate a custom Laracombee class

This creates a new class in app/Laracombee.

Available Methods

Laracombee generally follows Recombee naming conventions.

Users

• Laracombee::deleteUser($userId)
• Laracombee::mergeUsersWithId($targetUserId, $sourceUserId)
• Laracombee::listUsers($options = [])
• Laracombee::addUserProperty($property, $type)
• Laracombee::deleteUserProperty($property)
• Laracombee::setUserValues($userId, $fields)
• Laracombee::getUserValues($userId)

Items

• Laracombee::deleteItem($itemId)
• Laracombee::listItems($options = [])
• Laracombee::addItemProperty($property, $type)
• Laracombee::deleteItemProperty($property)
• Laracombee::setItemValues($itemId, $fields)
• Laracombee::getItemValues($itemId)
• Laracombee::getItemPropertyInfo($propertyName)

User-item interactions

• Laracombee::addDetailView($userId, $itemId, $options = [])
• Laracombee::deleteDetailView($userId, $itemId, $options = [])
• Laracombee::listItemDetailViews($itemId)
• Laracombee::listUserDetailViews($userId)
• Laracombee::addPurchase($userId, $itemId, $options = [])
• Laracombee::deletePurchase($userId, $itemId, $options = [])
• Laracombee::addRating($userId, $itemId, $rating, $options = [])
• Laracombee::deleteRating($userId, $itemId, $options = [])
• Laracombee::listItemRatings($itemId)
• Laracombee::listUserRatings($userId)
• Laracombee::addCartAddition($userId, $itemId, $options = [])
• Laracombee::deleteCartAddition($userId, $itemId, $options = [])
• Laracombee::addBookmark($userId, $itemId, $options = [])
• Laracombee::deleteBookmark($userId, $itemId, $options = [])
• Laracombee::setViewPortion($userId, $itemId, $portion, $options = [])
• Laracombee::deleteViewPortion($userId, $itemId, $options = [])
• Laracombee::listItemViewPortions($itemId)
• Laracombee::listUserViewPortions($userId)

Recommendations

• Laracombee::recommendItemsToUser($userId, $limit, $options = [])
• Laracombee::recommendUsersToUser($userId, $limit, $options = [])
• Laracombee::recommendTo($user, $limit = 10, $options = [])

Series

• Laracombee::addSeries($seriesId)
• Laracombee::insertToSeries($seriesId, $itemType, $itemId, $time)
• Laracombee::removeFromSeries($seriesId, $itemType, $itemId, $time)
• Laracombee::deleteSeries($seriesId)
• Laracombee::listSeries()
• Laracombee::listSeriesItems($seriesId)

Utility

• Laracombee::batch($requests)
• Laracombee::send($request)
• Laracombee::resetDatabase()

Extending the Package

If you want to tailor the behavior of the package, you can extend AbstractRecombee and implement your own send() method.

This is useful if you want to customize error handling, request flow, or database targeting.

Multiple Recombee Databases

You can create additional Laracombee-style classes if you need to work with multiple Recombee databases from the same application.

The built-in generator can help you scaffold those classes:

Contributing

Thank you for considering contributing to the project. Please read the contribution guide.

License

This package is open-sourced software licensed under the MIT license.