Weave Code
Activeredis Laravel Package
directorytree/activeredis
ActiveRedis provides a simple, efficient, Eloquent-like active record API for interacting with Redis hashes in Laravel. Define models and create, update, delete, expire, and query records, with support for casts, events, timestamps, chunking, and searching.
An ActiveRecord implementation for Redis.
Frequently asked questions about Activeredis
- What is ActiveRedis and what problem does it solve in Laravel?
- ActiveRedis is a DirectoryTree package that adds an Eloquent-like active record layer over Redis hashes in Laravel. Instead of working with raw HSET, HGETALL, and SCAN commands, you define model classes and use create, find, update, delete, chunk, and limited search methods. It is aimed at hash-shaped, often ephemeral records such as visits, tokens, presence state, and dedupe markers, not at relational or reporting workloads.
- How do I install and configure ActiveRedis in a Laravel app?
- Install it with composer require directorytree/activeredis, then create a model class that extends DirectoryTree\ActiveRedis\Model. Add a dedicated Redis connection entry in config/database.php and point the model at that connection. Declare any queryable attributes in the model's $searchable array before writing records, because searchable schema is effectively write-once.
- Which Laravel, PHP, and Redis versions does ActiveRedis support?
- The README lists PHP 8.1 or newer, Laravel 9.0 or newer, and Redis 3.0 or newer. That covers a mainstream modern Laravel matrix, but you should verify current tags and constraints on Packagist before scheduling work. The package is maintained by a single vendor, so pinning versions and reviewing releases is prudent.
- Do I need a dedicated Redis connection for ActiveRedis?
- Yes, treat a dedicated Redis connection or database as a hard requirement rather than a suggestion. ActiveRedis queries use SCAN over the keyspace, so sharing a database with cache, sessions, or queues makes queries slow and can affect unrelated workloads. The key scheme also assumes predictable prefixes, which is easier to control in an isolated connection.
- How do I create, update, and delete ActiveRedis models?
- Create records with Model::create([...]) and update by assigning attributes and saving the model. Delete individual records with the model's delete method or destroy by key. Be careful with create options such as force, which can delete an existing record on a duplicate key and is destructive rather than idempotent. Wrap create paths carefully and handle DuplicateKeyException explicitly.
- How does querying and searching work in ActiveRedis?
- Queries are backed by Redis SCAN with MATCH on a key prefix; COUNT is only a hint, not a limit. You can filter on attributes declared in $searchable, but there is no where on undeclared attributes, no orderBy, no true limit, no joins, and no transactional boundary. chunk() exists but the README warns chunk sizes are non-deterministic, so do not rely on stable page sizes.
- How do I set a TTL or expire an ActiveRedis record?
- ActiveRedis exposes setExpiry on models so you can attach a Redis TTL to a hash key. This is useful for ephemeral entities such as tokens, sessions, presence records, and dedupe markers. Remember that expiry is per key, so plan how indexes or searchable lists stay consistent when records disappear.
- What are the production risks of using ActiveRedis?
- The biggest risk is query cost: every collection read walks the keyspace with SCAN, so performance degrades linearly as keys grow. Searchable attributes are indexed at write time and are not safely changeable or backfillable, and non-atomic hash-plus-index writes can cause index drift. The force create option is destructive, reserved characters like colon and asterisk must be validated at the application boundary, and Redis Cluster can break the SCAN assumptions. Adoption is low, so expect to own maintenance or fork under MIT if needed.
- How should I test ActiveRedis models in Laravel?
- Integration tests against a real, isolated Redis database are the most reliable approach because SCAN, TTL, and hash behavior are central to the package. Flush the test database between tests and cover casts, timestamps, model events, expiry, and searchable-index updates. Mocking Redis SCAN semantics tends to hide the exact drift and prefix issues you need to catch.
- What are alternatives to ActiveRedis for Redis active record in Laravel?
- You can use Laravel's Redis facade or predis/phpredis directly for hash operations, though you lose the model API. For query-heavy or relational entities, a relational database with Eloquent is usually the better fit, with Redis kept as a cache. ActiveRedis occupies a narrow niche for hash-shaped, ephemeral records, so evaluate whether Redis should be your system of record before adopting it.
Weaver
How can I help you explore Laravel packages today?