Caching

Introduction

Streams Core provides a convenient API to link Laravel cache data to a Stream. When caching in this way, you can flush all cached items related to a Stream together.

Configuration

//streams/examples.json
{
    "config": {
        "cache": {
            "enabled": "true",
            "store": "default",
            "ttl": 3600
        }
    }
}

Cache Usage

The Cache Instance

To obtain a Stream-linked cache instance, you may use the cache() method on the desired Stream instance:

$cache = Streams::make('examples')->cache();

$cache->get('key');

Retrieving Items

Use the get method to retrieve items from the cache. If the item does not exist in the cache, null will be returned. You may pass a second argument specifying the default value to return if the item doesn't exist:

$cache = Streams::make('examples')->cache();

$value = $cache->get('key');

$value = $cache->get('key', 'default');

You may also pass a closure as the default value. The get method will return the closure result if the specified item does not exist in the cache. Using a closure allows you to defer the retrieval of expensive default values until they are needed:

$stream = Streams::make('examples');

$value = $stream->cache()->get('key', function () use ($stream) {
    return $stream->entries()->all();
});

Checking Items

Use the exists method to check if an item exists in cache:

if (Streams::make('examples')->cache()->has('key')) {
    // We have it!
}

Incrementing/Decrementing Values

Use the increment and decrement methods to increment or decrement the value of cached integer value:

$cache = Streams::make('examples')->cache();

$cache->increment('key');
$cache->increment('key', $amount);

$cache->decrement('key');
$cache->decrement('key', $amount);

Retrieve & Store

Use the remember method to retrieve an item from the cache and store a default value if the requested item doesn't exist.

$value = Streams::make('examples')->cache()->remember('key', $seconds, function () {
    return Streams::entries('examples')->get();
});

Retrieve & Delete

Use the pull method to retrieve an item from the cache and then delete the item.

$value = Streams::make('examples')->cache()->pull('key');

Storing Items

Use the put method to store items in the cache:

Streams::make('examples')->cache()->put('key', 'value', $seconds);

You can also pass a DateTime instance instead of seconds:

Streams::make('examples')->cache()->put('key', 'value', now()->addMinutes(10));

If the storage time is not passed to the put method, the item will be stored indefinitely:

Streams::make('examples')->cache()->put('key', 'value');

Store If Not Present

Use the add method to store items in the cache only if they do not already exist:

Streams::make('examples')->cache()->add('key', 'value', $seconds);

Store Forever

Use the forever method to store items in the cache indefinitely:

Streams::make('examples')->cache()->forever('key', 'value');

Items that are stored "forever" may be removed under some circumstances.

Removing Items

Use the forget method to remove items from the cache:

Streams::make('examples')->cache()->forget('key');

You can also remove items by providing a zero or negative number of seconds:

Streams::make('examples')->cache()->put('key', 'value', 0);

Streams::make('examples')->cache()->put('key', 'value', -5);

Stream entry changes automatically forget/flush cache items.

Removing All Items

You can clear the entire cache using the flush method:

Streams::make('examples')->cache()->flush();

The flush method only flushes linked cache.