unionworx/laravel-serializes-models-with-cache

This package provides a drop-in replacement for Laravel's SerializesModels trait that leverages your application's cache when unserializing models.

0.3.0 2026-06-02 14:30 UTC

Requires

• php: ^8.3
• illuminate/database: ^10.0|^11.0|^12.0|^13.0
• illuminate/queue: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^8.37|^9.17|^10.11|^11.1
• phpunit/phpunit: ^9.6|^10.5|^11.5|^12.5|^13.0

MIT

• Christopher Carranza

• cache
• laravel
• models
• unionworx
• serializes
• laravel-serializes-models-with-cache

README

This package provides a drop-in replacement for Laravel's SerializesModels trait that leverages your application's cache when unserializing models.

Installation

You can install the package via composer:

composer require unionworx/laravel-serializes-models-with-cache

Compatibility

• Laravel: 10.x, 11.x, 12.x, 13.x
• PHP: ^8.3

Usage

To use the SerializesModelsWithCache trait, simply replace Laravel's SerializesModels trait with SerializesModelsWithCache in your classes:

use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use UnionWorx\LaravelSerializesModelsWithCache\SerializesModelsWithCache;
use App\Models\Message;

class SendMessage
{
    use Dispatchable, InteractsWithQueue, SerializesModelsWithCache;
    
    public Message $message;

    public function handle()
    {
        // Your job logic
    }
}

Under the hood this uses most of the default behavior of the SerializesModels trait, but will attempt to retrieve the model from the cache before querying the database. This uses the remember feature of the Laravel cache to retrieve the model from the cache or uses the default SerializesModels behavior and stores the result.

Attributes

You can further customize the caching behavior using attributes:

• CacheKey: Define a custom cache key for a specific property.
• CacheTTL: Set a custom Time-To-Live (TTL) for the cache entry of a property.
• CacheSkip: Skip caching for a specific property.

use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheKey;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheTTL;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheSkip;
use App\Models\User;
use App\Models\Message;

class SendMessage
{
    use Dispatchable, InteractsWithQueue, SerializesModelsWithCache;

    #[CacheKey(key: 'custom_key_{id}')]
    #[CacheTTL(ttl: 120)]
    public Message $message;

    #[CacheSkip]
    public User $user;

    public function handle()
    {
        // Your job logic
    }
}

Methods

Alternatively, you can use the cacheKey, cacheTTL, and cacheSkip methods to customize the caching behavior:

use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheKey;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheTTL;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheSkip;
use App\Models\User;
use App\Models\Message;

class SendMessage
{
    use Dispatchable, InteractsWithQueue, SerializesModelsWithCache;

    public Message $message;

    public User $user;

    public function handle()
    {
        // Your job logic
    }
    
    public function cacheKey(string $propertyName, mixed $id): ?string
    {
        if ($propertyName === 'message') {
            return 'custom_key_' . $id;
        }
    }
    
    public function cacheTTL(): array|DateInterval|DateTimeInterface|int|null
    {
        return [
            'message' => 120,
        ];
    }
    
    public function cacheSkip(): ?array
    {
        return [
            'user',
        ];
    }
}

Cache Prefix

By default, model restores are cached using a versioned key derived from the full Laravel ModelIdentifier payload. The generated key includes the model class, id, connection, loaded relations, and collection class when present, so restores with different relation graphs do not share the same cache entry. The generated key format starts with model_restore_v2_.

The generated default key is also binary-safe for non-UTF-8 queueable identifiers, including binary string IDs and associative composite identifiers.

If you provide a #[CacheKey] attribute or a cacheKey() method, that explicit key still wins exactly as provided. For generated default keys, you can further isolate the cache by adding a cachePrefix() method to your class. The prefix applies only to generated default keys and does not modify explicit custom keys.

use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheKey;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheTTL;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheSkip;
use App\Models\Message;

class SendMessage
{
    use Dispatchable, InteractsWithQueue, SerializesModelsWithCache;

    #[CacheKey(key: 'custom_key_{id}')]
    public Message $message;

    public function handle()
    {
        // Your job logic
    }
    
    public function cachePrefix(): ?string
    {
        return get_class($this);
    }
}

Cache Store

By default, the cache store used is the default cache store defined in your Laravel configuration. You can override this by adding a cacheStoreName method to your class. The selected store is used for both generated default keys and explicit custom keys.

use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheKey;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheTTL;
use UnionWorx\LaravelSerializesModelsWithCache\Attributes\CacheSkip;
use App\Models\Message;

class SendMessage
{
    use Dispatchable, InteractsWithQueue, SerializesModelsWithCache;

    #[CacheKey(key: 'custom_key_{id}')]
    public Message $message;

    public function handle()
    {
        // Your job logic
    }
    
    public function cacheStoreName(): ?string
    {
        return 'file';
    }
}

Testing

You can run the package tests via composer:

composer test

Changelog

Please see CHANGELOG for more information on recent changes.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Christopher Carranza

License

MIT. Please see License File for more information.