README

A Laravel package for seamless integration with Recocube's recommendation engine API. This package provides an elegant way to fetch personalized product recommendations based on shopping cart contents, individual products, categories, and user behavior.

Requirements

PHP 8.1 or higher
Laravel 10.0 or higher

Installation

You can install the package via composer:

composer require ravols/laravel-recocube

Publish the config file with:

php artisan vendor:publish --tag="laravel-recocube-config"

This is the contents of the published config file:

return [
    'api_key' => env('RECOCUBE_API_KEY', ''),
    'api_retail_client_id' => env('RECOCUBE_API_RETAIL_CLIENT_ID', ''),
    'api_url' => env('RECOCUBE_API_URL', 'https://recocube.test/api'),
    'api_version' => env('RECOCUBE_API_VERSION', 'v1'),
];

Add your Recocube credentials to your .env file:

RECOCUBE_API_KEY=your-api-key
RECOCUBE_API_RETAIL_CLIENT_ID=your-retail-client-id
RECOCUBE_API_URL=https://api.recocube.com/api
RECOCUBE_API_VERSION=v1

Usage

Fetching Recommendations by Cart

Get product recommendations based on the current shopping cart contents:

use Ravols\LaravelRecocube\Facades\LaravelRecocube;
use Ravols\LaravelRecocube\Data\RecoCartItem;
use Ravols\LaravelRecocube\Data\RecoCartItemsCollection;

// Create cart items
$cartItems = new RecoCartItemsCollection([
    new RecoCartItem(product_id: 123, quantity: 2),
    new RecoCartItem(product_id: 456, quantity: 1),
]);

// Or add items one by one
$cartItems = new RecoCartItemsCollection();
$cartItems->addItem(new RecoCartItem(product_id: 123, quantity: 2));
$cartItems->addItem(new RecoCartItem(product_id: 456, quantity: 1));

// Fetch recommendations
$recommendations = LaravelRecocube::fetchRecoByCart($cartItems);

Fetching Recommendations by Product

Get recommendations based on a single product (coming soon):

use Ravols\LaravelRecocube\Facades\LaravelRecocube;

$productId = 123;
$recommendations = LaravelRecocube::fetchRecoByProduct($productId);

Fetching Recommendations by Category

Get recommendations for a specific product category (coming soon):

use Ravols\LaravelRecocube\Facades\LaravelRecocube;

$categoryId = 10;
$recommendations = LaravelRecocube::fetchRecoByCategory($categoryId);

Fetching Recommendations by User

Get personalized recommendations for a specific user (coming soon):

use Ravols\LaravelRecocube\Facades\LaravelRecocube;

$userId = 42;
$recommendations = LaravelRecocube::fetchRecoByUser($userId);

Working with RecoCartItemsCollection

The RecoCartItemsCollection is a type-safe collection that only accepts RecoCartItem instances:

use Ravols\LaravelRecocube\Data\RecoCartItem;
use Ravols\LaravelRecocube\Data\RecoCartItemsCollection;

// Create an empty collection
$cartItems = new RecoCartItemsCollection();

// Add items using addItem()
$cartItems->addItem(new RecoCartItem(product_id: 100, quantity: 1));

// Add items using push()
$cartItems->push(new RecoCartItem(product_id: 200, quantity: 3));

// Add items using put()
$cartItems->put('key', new RecoCartItem(product_id: 300, quantity: 2));

// All standard Laravel Collection methods are available
$count = $cartItems->count();
$filtered = $cartItems->filter(fn($item) => $item->quantity > 1);

Example in a Controller

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Ravols\LaravelRecocube\Facades\LaravelRecocube;
use Ravols\LaravelRecocube\Data\RecoCartItem;
use Ravols\LaravelRecocube\Data\RecoCartItemsCollection;

class RecommendationController extends Controller
{
    public function getCartRecommendations(Request $request)
    {
        $cart = $request->user()->cart;

        // Build cart items collection from your cart
        $cartItems = new RecoCartItemsCollection();
        foreach ($cart->items as $item) {
            $cartItems->addItem(
                new RecoCartItem(
                    product_id: $item->product_id,
                    quantity: $item->quantity
                )
            );
        }

        // Get recommendations
        $recommendations = LaravelRecocube::fetchRecoByCart($cartItems);

        return view('recommendations', [
            'recommendations' => $recommendations
        ]);
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

ravols / laravel-recocube

Maintainers

Details