README

A high-performance Pure PHP Redis Object Mapper (OM) for Laravel, powered by RedisJSON and RediSearch. This library provides an Eloquent-like experience with zero external dependencies other than Redis itself.

Features

• Direct Redis Access: Performance-critical operations (find, save, update, delete) interact directly with Redis using JSON.GET/SET.
• Search & Pagination: Full support for RediSearch filtering, sorting, and various pagination styles.
• Transaction Support: Group multiple operations like (begin,commit,rollback).
• Atomic Updates: Partial updates are performed atomically using RedisJSON paths.
• Eager Loading: Supports record relationships (hasOne, hasMany) and eager loading with with().

Installation

Install the package via Composer:

composer require masan27/laravel-redis-om

Configuration

Complete the installation and publish the config file:

php artisan redis-om:install

This command will publish the config/redis_om.php file and add necessary environment variables to your .env.

return [
    'connection'   => env('REDIS_OM_CONNECTION', 'default'),
    'index_suffix' => 'index',
];

Creating Models

You can quickly generate a new Redis OM model class using the following artisan command:

php artisan redis-om:model {name}

Example:

php artisan redis-om:model User

This will create app/Models/RedisOM/User.php. You can also use subdirectories: php artisan redis-om:model Products/Electronic.

Migrating Indexes

Since this is a Schema-based OM, you must create RediSearch indexes before querying. Run the following command whenever you add or update the $index property in your models:

php artisan redis-om:migrate

Use --force to drop and recreate existing indexes.

Basic Usage

Defining a Model

namespace App\Models\RedisOM;

use Masan27\LaravelRedisOM\RedisOM;

class User extends RedisOM 
{
    protected array $index = [
        'name'   => 'TEXT',
        'email'  => 'TAG',
        'age'    => 'NUMERIC',
        'status' => 'TAG',
    ];
}

CRUD Operations

// Create
$user = User::create(['id' => 1, 'name' => 'Sian', 'status' => 'active']);

// Find
$user = User::find(1);

// Update
$user->status = 'inactive';
$user->save();

// Delete
$user->delete();

Querying

// Fluent Query Building
$users = User::query()
    ->where('status', 'active')
    ->where('age', '>=', 18)
    ->whereStartsWith('name', 'Sia')
    ->orderBy('age', 'desc')
    ->get();

// Pagination
$paginated = User::query()->paginate(15);

Debugging & Query Logging

Query Log

You can enable the query log to capture all raw Redis commands executed during a request. This is useful for debugging and performance profiling.

use Masan27\LaravelRedisOM\RedisOM;

// Enable logging
RedisOM::enableQueryLog();

// Run some queries
$user = User::find(1);
$activeUsers = User::where('status', 'active')->get();

// Get the log
$logs = RedisOM::getQueryLog();
/*
[
    [
        'query'      => 'JSON.GET users:1',
        'time'       => 0.45, // in milliseconds
        'connection' => 'default'
    ],
    [
        'query'      => 'FT.SEARCH users:index "@status:{active}" LIMIT 0 10',
        'time'       => 1.2,
        'connection' => 'default'
    ]
]
*/

// Clear the log
RedisOM::flushQueryLog();

// Disable logging
RedisOM::disableQueryLog();

Raw Query Preview

If you want to see the FT.SEARCH command that will be executed by the query builder without actually running it:

$query = User::where('status', 'active')->where('age', '>', 20);

echo $query->getRawQuery();
// Output: FT.SEARCH users:index "@status:{active} @age:[(20 +inf]" LIMIT 0 10

Documentation & Examples

Detailed usage examples:

• CRUD Operations — Finding, saving, updating, and deleting.
• Querying & Pagination — Filtering, sorting, and pagination styles.
• Relations — Defining and using relationships.
• Transactions — Atomic operations with MULTI/EXEC.

License

Custom Fork-Only License. Please see the LICENSE file for more information.