A Laravel integration for the Gorse recommendation engine. This package provides a seamless way to integrate Gorse's recommendation capabilities into your Laravel application.
- Easy integration with Laravel's Eloquent models
- Automatic synchronization of users and items with Gorse
- Support for feedback tracking
- Simple recommendation retrieval
- Command-line tools for bulk synchronization
- PHP 8.1 or higher
- Laravel 11.x or 12.x
- A running Gorse instance
You can install the package via composer:
composer require janyksteenbeek/laravel-gorseAfter installation, publish the configuration file:
php artisan vendor:publish --tag="gorse-config"Add the following environment variables to your .env file:
GORSE_API_KEY=your-api-key
GORSE_ENDPOINT=http://your-gorse-instance:8087
# Optional: Disable SSL verification for development/self-signed certificates
GORSE_VERIFY_SSL=false
# Optional: Enable automatic synchronization with Gorse
GORSE_AUTO_SYNC=false
# Optional: Enable automatic model resolving (default: true)
GORSE_RESOLVING_ENABLED=trueBy default, SSL certificate verification is enabled for security. However, in development environments or when using self-signed certificates, you may need to disable it. You can do this by setting GORSE_VERIFY_SSL=false in your .env file.
Note: It's recommended to keep SSL verification enabled in production environments.
To make a model recommendable (e.g., products, articles), use the HasGorseFeedback trait:
use JanykSteenbeek\LaravelGorse\Traits\HasGorseFeedback;
class Product extends Model
{
use HasGorseFeedback;
// Optional: Customize Gorse integration
protected function gorseCategories(): array
{
return ['products', $this->category];
}
protected function gorseLabels(): array
{
return [$this->type, $this->brand];
}
}To enable users to receive recommendations, use the HasGorseRecommendations trait:
use JanykSteenbeek\LaravelGorse\Traits\HasGorseRecommendations;
class User extends Model
{
use HasGorseRecommendations;
protected function gorseLabels(): array
{
return [self::class, $this->country];
}
}// Get recommendations for a user
$recommendations = $user->recommendations(10); // Get 10 recommendations
// Get category-specific recommendations
$recommendations = $user->categoryRecommendations('electronics', 10);
// Get popular items
$recommendations = $user->popularItems(10);
// Get popular items in a category
$recommendations = $user->popularItemsByCategory('electronics', 10);
// Get session-based recommendations
$recommendations = $user->sessionRecommendations([
[
'FeedbackType' => 'click',
'ItemId' => 'product:123',
'Timestamp' => '2024-03-20T12:00:00Z'
]
], 10);
// Get category-specific session recommendations
$recommendations = $user->sessionCategoryRecommendations('electronics', [
[
'FeedbackType' => 'click',
'ItemId' => 'product:123'
]
], 10);
// Get similar users (neighbors)
$similarUsers = $user->userNeighbors(10);
// Record feedback
$user->feedback($product, 'like');The package supports automatic synchronization of your models with Gorse. When enabled, any changes to your models (create, update, delete) will be automatically synchronized with Gorse. You can enable this feature by setting GORSE_AUTO_SYNC=true in your .env file.
By default, when retrieving recommendations, the package will automatically resolve the recommended items into their respective Eloquent models. This means you'll get a collection of actual model instances instead of just IDs. You can disable this feature by setting GORSE_RESOLVING_ENABLED=false in your .env file.
The package provides commands to manually sync your data with Gorse:
# Sync all users
php artisan gorse:sync-users --model=App\\Models\\User --chunk=100
# Sync all items
php artisan gorse:sync-items --model=App\\Models\\Product --chunk=100The --chunk option allows you to specify how many records should be processed at once (default: 100).
You can also use the Gorse facade directly:
use JanykSteenbeek\LaravelGorse\Facades\Gorse;
// Get recommendations (resolved to model instances)
$recommendations = Gorse::getRecommendations($userId, 10);
// Get raw recommendations without model resolution
$rawRecommendations = Gorse::raw()->getRecommendations($userId, 10);
// Returns a Collection of: [['Id' => 'Product:1', 'Score' => 0.95], ...]
// All recommendation methods return Collections, making them Laravel-friendly
$rawRecommendations->pluck('Score')->avg(); // Get average score
$rawRecommendations->sortByDesc('Score'); // Sort by score
$rawRecommendations->filter(fn ($item) => $item['Score'] > 0.5); // Filter by score
// Or use resolveModels() to control resolution
$rawRecommendations = Gorse::resolveModels(false)->getRecommendations($userId, 10);
// Get category recommendations
$recommendations = Gorse::getCategoryRecommendations($userId, 'electronics', 10);
// Get popular items
$recommendations = Gorse::getPopularItems(10, $userId);
// Get popular items in category
$recommendations = Gorse::getPopularItemsByCategory('electronics', 10, $userId);
// Get session recommendations
$recommendations = Gorse::getSessionRecommendations($feedback, 10);
// Get session recommendations in category
$recommendations = Gorse::getSessionCategoryRecommendations('electronics', $feedback, 10);
// Get similar users
$recommendations = Gorse::getUserNeighbors($userId, 10);
// Insert feedback
Gorse::insertFeedback('like', $userId, $itemId);All recommendation methods return Laravel Collections, regardless of whether model resolution is enabled. This means you can use all of Laravel's Collection methods on both resolved and raw results:
// Raw response with scores (as Collection)
$rawRecommendations = Gorse::raw()->getRecommendations($userId, 10);
// Use Collection methods on raw results
$highScoring = $rawRecommendations
->filter(fn ($item) => $item['Score'] > 0.8)
->sortByDesc('Score')
->values();
$averageScore = $rawRecommendations->pluck('Score')->avg();
// Resolved to models with scores (as Collection)
$recommendations = Gorse::getRecommendations($userId, 10);
// Use Collection methods on resolved models
$highScoring = $recommendations
->filter(fn ($model) => $model->gorse_score > 0.8)
->sortByDesc('gorse_score')
->values();
$averageScore = $recommendations->pluck('gorse_score')->avg();The MIT License (MIT). Please see License File for more information.