README.md
# Cache Refresh
[](https://packagist.org/packages/laragear/cache-refresh)
[](https://github.com/Laragear/CacheRefresh/actions)
[](https://codecov.io/gh/Laragear/CacheRefresh)
[](https://codeclimate.com/github/Laragear/CacheRefresh/maintainability)
[](https://sonarcloud.io/dashboard?id=Laragear_CacheRefresh)
[](https://laravel.com/docs/9.x/octane#introduction)
Refresh items in your cache without data races.
```php
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Collection;
use App\Models\Message;
public function send(Message $message)
{
Cache::refresh(
$message->to,
fn ($messages) => Collection::wrap($messages)->push($message)
);
}
```
## Become a sponsor
[](https://github.com/sponsors/DarkGhostHunter)
Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you
can **[spread the word!](http://twitter.com/share?text=I%20am%20using%20this%20cool%20PHP%20package&url=https://github.com%2FLaragear%2FCacheRefresh&hashtags=PHP,Laravel)**
## Requirements
* PHP 8 or later
* Laravel 9, 10 or later
* Cache Driver with Lock support (*).
> **Warning** You can still use Cache Refresh without a driver that supports locking, but bear in mind, **refreshing won't be atomic**.
## Installation
You can install the package via Composer:
```bash
composer require laragear/cache-refresh
```
## Usage
Cache Refresh will retrieve a key value from your cache store that you can edit using a callback. This callback is free to change the value and return it to be persisted.
When the cached value doesn't exist, like when is first called, you will receive `null`, so remember to _un-null_ the value when is first called.
```php
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Collection;
use App\Models\Message;
public function send(Message $message)
{
// Add the incoming message to a list of messages, refreshing the overall list.
$messages = Cache::refresh(
$message->to,
function (?Collection $messages) use ($message) {
return Collection::wrap($messages)->push($message);
},
60 * 5
);
return 'Messages has been queued';
}
```
### Custom Expiration time
The callback also receives an `Expire` instance, which will allow you to change the expiration time of the key inside the callback.
```php
use Illuminate\Support\Facades\Cache;
use Laragear\CacheRefresh\Expire;
use App\Models\Mission;
Cache::refresh('mission', function ($mission, Expire $expire) {
$mission ??= new Mission();
if ($mission->ongoing()) {
// Set a new expiration time.
$expire->at(today()->endOfDay());
}
if ($mission->completed()) {
// Expire the value immediately.
$expire->now();
}
if ($mission->isVeryDifficult()) {
// Put it forever.
$expire->never();
}
return $mission;
}, 60 * 5);
```
### Custom Lock configuration
You can omit a callback to manage the lock time and the waiting time using `lock()` and `waitFor()`, respectively, and issue the callback using `put()`.
```php
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Collection;
use App\Models\Message;
Cache::refresh('mission')->lock(60)->waitFor(10)->put(fn ($value) => ..., 60 * 5);
```
## PhpStorm stubs
For users of PhpStorm, there is a stub file to aid in macro autocompletion for this package. You can publish them using the `phpstorm` tag:
```shell
php artisan vendor:publish --provider="Laragear\CacheRefresh\CacheRefreshServiceProvider" --tag="phpstorm"
```
The file gets published into the `.stubs` folder of your project. You should point your [PhpStorm to these stubs](https://www.jetbrains.com/help/phpstorm/php.html#advanced-settings-area).
## 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 darkghosthunter@gmail.com instead of using the issue tracker.
# License
This specific package version is licensed under the terms of the [MIT License](LICENSE.md), at time of publishing.
[Laravel](https://laravel.com) is a Trademark of [Taylor Otwell](https://github.com/TaylorOtwell/). Copyright © 2011-2022 Laravel LLC.