Skip to content

Commit

Permalink
undocument cache tags due to complexity of implementation
Browse files Browse the repository at this point in the history
  • Loading branch information
taylorotwell committed Sep 12, 2023
1 parent fca85ee commit 63dde39
Showing 1 changed file with 0 additions and 50 deletions.
50 changes: 0 additions & 50 deletions cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,6 @@
- [Storing Items In The Cache](#storing-items-in-the-cache)
- [Removing Items From The Cache](#removing-items-from-the-cache)
- [The Cache Helper](#the-cache-helper)
- [Cache Tags](#cache-tags)
- [Storing Tagged Cache Items](#storing-tagged-cache-items)
- [Accessing Tagged Cache Items](#accessing-tagged-cache-items)
- [Removing Tagged Cache Items](#removing-tagged-cache-items)
- [Pruning Stale Cache Tags](#pruning-stale-cache-tags)
- [Atomic Locks](#atomic-locks)
- [Driver Prerequisites](#lock-driver-prerequisites)
- [Managing Locks](#managing-locks)
Expand Down Expand Up @@ -267,51 +262,6 @@ When the `cache` function is called without any arguments, it returns an instanc
> **Note**
> When testing call to the global `cache` function, you may use the `Cache::shouldReceive` method just as if you were [testing the facade](/docs/{{version}}/mocking#mocking-facades).
<a name="cache-tags"></a>
## Cache Tags

> **Warning**
> Cache tags are not supported when using the `file`, `dynamodb`, or `database` cache drivers. Furthermore, when using multiple tags with caches that are stored "forever", performance will be best with a driver such as `memcached`, which automatically purges stale records.
<a name="storing-tagged-cache-items"></a>
### Storing Tagged Cache Items

Cache tags allow you to tag related items in the cache and then flush all cached values that have been assigned a given tag. You may access a tagged cache by passing in an ordered array of tag names. For example, let's access a tagged cache and `put` a value into the cache:

Cache::tags(['people', 'artists'])->put('John', $john, $seconds);

Cache::tags(['people', 'authors'])->put('Anne', $anne, $seconds);

<a name="accessing-tagged-cache-items"></a>
### Accessing Tagged Cache Items

Items stored via tags may not be accessed without also providing the tags that were used to store the value. To retrieve a tagged cache item, pass the same ordered list of tags to the `tags` method and then call the `get` method with the key you wish to retrieve:

$john = Cache::tags(['people', 'artists'])->get('John');

$anne = Cache::tags(['people', 'authors'])->get('Anne');

<a name="removing-tagged-cache-items"></a>
### Removing Tagged Cache Items

You may flush all items that are assigned a tag or list of tags. For example, this statement would remove all caches tagged with either `people`, `authors`, or both. So, both `Anne` and `John` would be removed from the cache:

Cache::tags(['people', 'authors'])->flush();

In contrast, this statement would remove only cached values tagged with `authors`, so `Anne` would be removed, but not `John`:

Cache::tags('authors')->flush();

<a name="pruning-stale-cache-tags"></a>
### Pruning Stale Cache Tags

> **Warning**
> Pruning stale cache tags is only necessary when using Redis as your application's cache driver.
In order to properly prune stale cache tag entries when using the Redis cache driver, Laravel's `cache:prune-stale-tags` Artisan command should be [scheduled](/docs/{{version}}/scheduling) in your application's `App\Console\Kernel` class:

$schedule->command('cache:prune-stale-tags')->hourly();

<a name="atomic-locks"></a>
## Atomic Locks

Expand Down

11 comments on commit 63dde39

@kohenkatz
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that tags will be removed from Laravel 11+, or will they remain as an undocumented feature?

@timwassenburg
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious, is there any background information on this change?

@TheDeadCode
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quite on odd change for such a good feature. Are there plans to phase it out? I hope not :o

@francoism90
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems really weird, aren't some packages using this heavily? It's also pretty useful for caching model instances.

@bmckay959
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Curious as well on whether tags are being deprecated? Or just removed from documentation? My system relies on this heavily and need to know if I should build my own tags system if it is being removed.

@francoism90
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

livewire/livewire#7141

What's the recommended thing to do? Not use caching tags at all?

@Etra-0
Copy link

@Etra-0 Etra-0 commented on 63dde39 Nov 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any word on this?

@shaedrich
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@francoism90
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shaedrich Yeah, but the problem is that packages are using this for years now.

@shaedrich
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe, @zengbo's changes can be moved to a package … 🤔

@binaryfire
Copy link

@binaryfire binaryfire commented on 63dde39 Jan 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@taylorotwell We have loads of apps that rely on cache tags.... It's a crucial feature for managing caching in any large scale app, or multi-tenant setups etc.

If you're open to breaking changes in v11, I think refactoring tags to work how they do in every other platform (i.e. much more simply) would be great. The complexity in Laravel comes from how multiple tags work. The readme of this package explains it well: https://github.com/swayok/alternative-laravel-cache.

I never understood the logic behind Laravel's implementation. Tags should be independent - i.e. you can tag a single cache object with multiple tags, then purge that object using any of those tags. So you could tag a post with posts and tenant_1, and if you purged either the posts or tenant_1 tag that object would be removed.

Please sign in to comment.