Bucket

Save items in a bucket, retrieve them later.

use Laragear\Bucket\Facades\Buckets;
use App\Models\Message;

public function send(Message $message)
{
    $bucket = Buckets::get($message->receiver)->add($message)->save();
    
    if ($bucket->isNew()) {
        $message->receiver->notify(new MessagesReceived($bucket))->delay(300);
    }
}

Keep this package free

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word!

Requirements

• Laravel 9.x, or later
• PHP 8.0 or later

Installation

You can install the package via Composer:

composer require laragear/bucket

Usage

A bucket is like a living box where you add items that persist across requests. You interact with Buckets mainly using the Buckets facade.

Start creating one Bucket using get() with a unique key to identify it. Once you add items using add(), you may save the bucket using save(), otherwise it will be done automatically once destroyed.

use Laragear\Bucket\Facades\Buckets;
use App\Models\Message;

public function send(Message $message)
{
    // Save the message into the bucket for the receiver ID.
    Buckets::get($message->receiver)->add($message)->save();
}

You can later retrieve the same bucket and its items using the Bucket facade and the get method, along with its identifier.

use Laragear\Bucket\Facades\Buckets;
use App\Models\Message;
use App\Models\User;

public function received(User $receiver)
{
    // Show all messages receives so far.
    $messages = Buckets::get($receiver)->items();
}

Key helpers

While you may use a simple string to identify a Bucket, you can just use a Model, Request or Session instance as a keys:

• A Model will use its class name and primary key.
• A Request will use its fingerprint.
• A Session will use its identifier.

use Laragear\Bucket\Facades\Buckets;
use \Illuminate\Http\Request;
use App\Models\Message;
use App\Models\User;

public function received(Request $request, User $receiver)
{
    // Use the request fingerprint.
    Buckets::get($request);
    
    // Use the user session.
    Buckets::get($request->session());
    
    // Use a particular model instance.
    Buckets::get($receiver);
    
    // ...
}

Adding items

A Bucket uses a Collection underneath to save each item added to it. After adding them, you can retrieve them all using items().

use Laragear\Bucket\Facades\Buckets;

$bucket = Buckets::get('messages')->add('Hello!');

$bucket->add('World!');

$bucket->items(); // ["Hello!", "World!"]

Changes made to the items directly will not propagate to the Bucket instance. You may want to use save(true) on the bucket to force saving any changes.

All the items in the Collection will be serialized when cached. For the case of Eloquent Models, a Bucket will intelligently use an Eloquent Collection if your first item is an Eloquent Model, or an Eloquent Collection itself. This will allow the Bucket to serialize the model identifiers so these can be retrieved later, optimizing the cache storage.

use Laragear\Bucket\Facades\Buckets;
use App\Model\Message;

$messages = Message::where('is_read', false)->get();

$bucket = Buckets::get('messages')->add($messages)->save();

For further optimizations, you can add withoutRelations() to unload the Model relations before adding them to the Bucket.

On create callback

Add a callback to the created() method, which will save the bucket and execute the callback only if it's new in the cache.

use Laragear\Bucket\Facades\Buckets;
use App\Notificationes\MessagesReceived;

public function received(User $receiver)
{
    Buckets::get($message->receiver)
        ->add($message)
        ->created(function ($bucket) use ($message) {
            // This bucket is new. Capture all messages for 5 minutes.
            $message->receiver->notify((new MessagesReceived($bucket))->delay(60 * 5));
        });
}

Deleting a bucket

After you're done with a Bucket, you can remove it from the cache using delete() from the Bucket instance itself.

use Laragear\Bucket\Facades\Buckets;

public function received(User $receiver)
{
    $bucket = Buckets::get($receiver);
    
    // ...
    
    $bucket->delete();
}

Alternatively, you may want to use pull() instead, which retrieves the Bucket from the Cache and forgets it in one method.

use Laragear\Bucket\Facades\Buckets;

public function received(User $receiver)
{
    $bucket = Buckets::pull($receiver);
    
    // ...
}

Lifetime

Bucket are persisted for a default of 15 minutes, which is the same maximum minutes to delay a Queued Job in Amazon SQS. You can set a Bucket with your own expiration time, or use forever() to keep it until the end of time.

use Laragear\Bucket\Facades\Buckets;

public function received(User $receiver)
{
    // Add an expiration time.
    Buckets::get($receiver)->expireAt(60 * 5);
    
    // Remember it forever
    Buckets::get($receiver)->forever();
}

Fresh instance

Sometimes you may have edited the bucket elsewhere, making the current instance stale. For these occasions, you can use fresh(), which will return a new fresh instance from the Cache.

use Laragear\Bucket\Facades\Buckets;

$bucket = Buckets::get($receiver)->add($message)->save();

// ...

$fresh = $bucket->fresh();

Advanced configuration

Bucket is intended to work out-of-the-box, but you can publish the configuration file for changing its defaults.

php artisan vendor:publish --provider="Laragear\Bucket\BucketServiceProvider" --tag="config"

You will get the bucket.php config file with this array:

<?php

return [
    'store' => null,
    'ttl' => 15 * 60,
    'prefix' => 'bucket',
];

Cache store

return [
    'store' => null,
];

The default cache store to use for handling Buckets. If null, it will use the application default.

You can override this at runtime using the store() method of the Buckets facade.

use Laragear\Bucket\Facades\Buckets;

Buckets::store('redis')->get('my_bucket');

Time-to-live

return [
    'ttl' => 15 * 60,
];

The default amount of time in seconds that each Bucket should live in the cache. When null, these will live forever.

Prefix

return [
    'prefix' => 'bucket',
];

The cache key prefix to use when storing buckets into the Cache. You may change it to avoid risks of collision with other cache keys.

Laravel Octane compatibility

• There are no singletons using a stale application instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.

There should be no problems using this package with Laravel Octane.

Security

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

License

This specific package version is licensed under the terms of the MIT License, at time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2022 Laravel LLC.