[Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command #8209

robfrawley · 2017-07-22T03:08:19Z

This PR documents the changes introduced in symfony/symfony#23451 and symfony/symfony#23603:

The addition of PruneableInterface
The variouse, concrete PruneableInterface::prune() implementations in ChainAdapter, FilesystemAdapter, PdoAdapter, PhpFilesAdapter, ChainCache, FilesystemCache, PdoCache, PhpFilesCache, and TagAwareAdapter.
The addition of CachePoolPruneCommand, invokable via cache:pool:prune. This command iterates over all services tagged cache.pool and calls the PruneableInterface::prune() method on those that implement PruneableInterface

Additionally, some language changes and cleanup has been implemented for the various cache docs. Of note are the following changes:

Additional note blocks for all caches that implement PruneableInterface
Addition of prune() description and usage example on the chain adapter
Addition of a tip about achieving better performance with the filesystem adapter by utilizing tmpfs or another ram disk solution
Fix for an incorrect use statement in the PHP array cache adapter code example
Addition of documentation page for PHP files adapter
Addition of a "pruning cache items" explanation and example on the main cache pools page

@fopen

…e) prune method and prune command (robfrawley) This PR was merged into the 3.4 branch. Discussion ---------- [Cache] Add (filesystem|phpfiles) cache (adapter|simple) prune method and prune command | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #21764, #21764 (comment) | License | MIT | Doc PR | symfony/symfony-docs#8209 As requested in #21764 (comment), this PR adds a `prune()` method to [`FilesystemTrait`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Traits/FilesystemTrait.php). This placement seems reasonable as it exposes the method in [`FilesystemAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/FilesystemAdapter.php) and [`FilesystemCache`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Simple/FilesystemCache.php). The return value is a `bool` representing either a partial or complete failure (when `false`) *or* complete success (when `true`). Once the API for the `prune` method is confirmed, I'll introduce a documentation PR, as well. --- *Stale-detection implementation:* The file modification time is used to determine if a cache item should be pruned. This seems reasonable, given the use of [`touch` in the common trait](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Traits/FilesystemCommonTrait.php#L90). Interestingly, though, the [`doFetch` method](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Traits/FilesystemTrait.php#L38) uses the timestamp saved at the top of the file itself to determine the stale state. Should this latter implementation be used for `prune` as well (or is the current one ok), for example: ```php foreach (new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($this->directory, \FilesystemIterator::SKIP_DOTS), \RecursiveIteratorIterator::LEAVES_ONLY, \RecursiveIteratorIterator::CATCH_GET_CHILD) as $file) { if ($h = @fopen($file, 'rb')) { if ($time >= (int) $expiresAt = fgets($h)) { fclose($h); if (isset($expiresAt[0])) { $okay = (@Unlink($file) && !file_exists($file)) && $okay; } } } } ``` Commits ------- f0d0c5f add (filesystem|phpfiles) cache (adapter|simple) prune method and prune command

robfrawley · 2017-08-14T03:43:59Z

components/cache/adapters/chain_adapter.rst

+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
+    for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
+    calling it's ``prune()`` method.


Note to self: should be "its". Duplicate issues in the other adapters with this note.

robfrawley · 2017-08-31T03:21:16Z

I require some insight from someone (@javiereguiluz, @xabbuh, or @nicolas-grekas, perhaps) as to an appropriate location for describing the new cache:pool:prune command. Perhaps a person more familiar with the documentation has a better idea as to where this new (cache-related, framework-bundle-located) command should exist in the documentation structure? Does it deserve its own page (likely no), or can it be added to an appropriate existing page?

Edit: Added a tip block at the end of the "Pruning Cache Items" section of the cache_pools.rst page briefly describing the cache:pool:prune command.

@nicolas-grekas

…ethod (robfrawley) This PR was merged into the 3.4 branch. Discussion ---------- [Cache] Add (pdo|chain) cache (adapter|simple) prune method | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | symfony/symfony-docs#8209 This is additional work toward making more cache implementations use the `PruneableInterface` contract. Specifically, this pull request focuses on `(Pdo|Chain)(Cache|Adapter)`, as suggested by @nicolas-grekas in #23451 (comment). Commits ------- b20a237 add (pdo|chain) cache (adapter|simple) prune method

@nicolas-grekas

…ethod (robfrawley) This PR was merged into the 3.4 branch. Discussion ---------- [Cache] Add (pdo|chain) cache (adapter|simple) prune method | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | symfony/symfony-docs#8209 This is additional work toward making more cache implementations use the `PruneableInterface` contract. Specifically, this pull request focuses on `(Pdo|Chain)(Cache|Adapter)`, as suggested by @nicolas-grekas in symfony/symfony#23451 (comment). Commits ------- b20a237 add (pdo|chain) cache (adapter|simple) prune method

Toflar · 2017-09-03T11:21:34Z

Hey @robfrawley, would you mind adding the same hint as in ChainAdapter for TagAwareAdapter too? See symfony/symfony#24075 😄

robfrawley · 2017-09-04T04:26:21Z

@Toflar Done. There is no dedicated page for TagAwareAdapter so I added the comment to the "Cache Invalidation" page talking about usage of TagAwareAdapter. Does that seem logical? Anywhere else you think it should be noted or any additional information on this page that should be added?

Toflar · 2017-09-04T11:00:18Z

I think that's perfect - thanks a lot!

…lar) This PR was submitted for the master branch but it was merged into the 3.4 branch instead (closes #24075). Discussion ---------- Implemented PruneableInterface on TagAwareAdapter | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | See comment on #23451 | License | MIT | Doc PR | Added a comment on symfony/symfony-docs#8209 The `ChainAdapter` already delegates the `prune()` calls. The `TagAwareAdapter` is a wrapping adapter too and should delegate the `prune()` calls just the same. Commits ------- b635b62 Implemented PruneableInterface on TagAwareAdapter

robfrawley · 2017-09-05T05:44:28Z

A comment about the new cache:pool:prune command has been added to the "Pruning Cache Items" section of the cache_pools.rst page. Moreover, the multiple commits have now been squashed. This is done from my end and ready for any review(s).

robfrawley · 2018-01-22T18:55:27Z

@javiereguiluz, @xabbuh, @nicolas-grekas: Do you guys intend to merge this documentation? It's becoming tiresome to continually rebase this over and over for past six months. If you need some aspect of it changed for inclusion, please advise. If you don't want it, let me know. Symfony 3.4 and 4.0 have been released; both versions include the functionality described here, so I think it makes sense to include. Regardless, can we wrap this up one way or the other? Thanks!

- note the addition of PruneableInterface - note the variouse, concrete PruneableInterface::prune() implementations in ChainAdapter, FilesystemAdapter, PdoAdapter, PhpFilesAdapter, ChainCache, FilesystemCache, PdoCache, PhpFilesCache, and TagAwareAdapter. - note the addition of CachePoolPruneCommand, invokable via cache:pool:prune. This command iterates over all services tagged cache.pool and calls the PruneableInterface::prune() method on those that implement PruneableInterface - rewording of some adapter text for clarity - additional note blocks for all caches that implement PruneableInterface - addition of prune() description and usage example on the chain adapter - addition of a tip about achieving better performance with the filesystem adapter by utilizing tmpfs or another ram disk solution - fix for an incorrect use statement in the PHP array cache adapter code example - addition of documentation page for PHP files adapter - addition of a "pruning cache items" explanation and example on the main cache pools page

robfrawley · 2018-01-22T23:59:13Z

Rebased again...

javiereguiluz · 2018-01-23T07:43:17Z

@robfrawley I'm really sorry that we didn't review and merge this earlier. Our resources are too limited ... but lately we're making an effort to merge things more quickly. In any case, your contribution is now merged. Thank you!

…dapter|simple) prune method and prune command (robfrawley, javiereguiluz) This PR was merged into the 3.4 branch. Discussion ---------- [Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command This PR documents the changes introduced in symfony/symfony#23451 and symfony/symfony#23603: - The addition of [`PruneableInterface`](https://github.com/symfony/cache/blob/master/PruneableInterface.php) - The variouse, concrete [`PruneableInterface::prune()`](https://github.com/symfony/cache/blob/master/PruneableInterface.php#L22) implementations in [`ChainAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/ChainAdapter.php), [`FilesystemAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/FilesystemAdapter.php), [`PdoAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/PdoAdapter.php), [`PhpFilesAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/PhpFilesAdapter.php),[ `ChainCache`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Simple/ChainCache.php), [`FilesystemCache`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Simple/FilesystemCache.php), [`PdoCache`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Simple/PdoCache.php), [`PhpFilesCache`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Simple/PhpFilesCache.php), and [`TagAwareAdapter`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Cache/Adapter/TagAwareAdapter.php). - The addition of [`CachePoolPruneCommand`](https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Command/CachePoolPruneCommand.php), invokable via `cache:pool:prune`. This command iterates over all services tagged `cache.pool` and calls the [`PruneableInterface::prune()`](https://github.com/symfony/cache/blob/master/PruneableInterface.php#L22) method on those that implement [`PruneableInterface`](https://github.com/symfony/cache/blob/master/PruneableInterface.php) Additionally, some language changes and cleanup has been implemented for the various cache docs. Of note are the following changes: - Additional `note` blocks for all caches that implement [`PruneableInterface`](https://github.com/symfony/cache/blob/master/PruneableInterface.php) - Addition of `prune()` description and usage example on the chain adapter - Addition of a `tip` about achieving better performance with the filesystem adapter by utilizing `tmpfs` or another ram disk solution - Fix for an incorrect `use` statement in the PHP array cache adapter code example - Addition of documentation page for PHP files adapter - Addition of a "pruning cache items" explanation and example on the main cache pools page Commits ------- 54a1e62 Typo 1322ffd Typos and wrapped long lines 5bea1e6 Fixed a typo eb70a36 Wrapped long lines ea29252 document cache pruning functionality - note the addition of PruneableInterface - note the variouse, concrete PruneableInterface::prune() implementations in ChainAdapter, FilesystemAdapter, PdoAdapter, PhpFilesAdapter, ChainCache, FilesystemCache, PdoCache, PhpFilesCache, and TagAwareAdapter. - note the addition of CachePoolPruneCommand, invokable via cache:pool:prune. This command iterates over all services tagged cache.pool and calls the PruneableInterface::prune() method on those that implement PruneableInterface - rewording of some adapter text for clarity - additional note blocks for all caches that implement PruneableInterface - addition of prune() description and usage example on the chain adapter - addition of a tip about achieving better performance with the filesystem adapter by utilizing tmpfs or another ram disk solution - fix for an incorrect use statement in the PHP array cache adapter code example - addition of documentation page for PHP files adapter - addition of a "pruning cache items" explanation and example on the main cache pools page

* 4.0: [symfony#8209] fix reference minor symfony#9114 Fixed the syntax of some internal references (javiereguiluz) Fixed the syntax of some internal references Mentioned the TargetPathTrait utility Removed some contents unnecessary when using Flex Added a mention to the createTable() method of the session handler Remove out-of-context rewrite rule tip Document cache pruning functionality Mention cachetool utility to clear OPcache cache from CLI Documented the use of PHP streams as the process input Update built_in_web_server.rst Add missing `bundles` sub-dir

robfrawley · 2018-01-23T23:29:49Z

@javiereguiluz Thanks for taking the time to review and merge this!

carsonbot added Status: Needs Review Cache labels Jul 22, 2017

This was referenced Jul 22, 2017

[Cache] Add (filesystem|phpfiles) cache (adapter|simple) prune method and prune command symfony/symfony#23451

Merged

[Cache] Add (pdo|chain) cache (adapter|simple) prune method symfony/symfony#23603

Merged

xabbuh added this to the 3.4 milestone Jul 25, 2017

HeahDude added Status: Needs Work and removed Status: Needs Review labels Jul 29, 2017

robfrawley commented Aug 14, 2017

View reviewed changes

robfrawley force-pushed the feature-document-cache-pruneable-additions branch from 397ef14 to bbe0f43 Compare August 14, 2017 05:39

carsonbot added Status: Needs Review and removed Status: Needs Work labels Aug 14, 2017

robfrawley force-pushed the feature-document-cache-pruneable-additions branch from bbe0f43 to 634902a Compare August 14, 2017 06:00

Toflar mentioned this pull request Sep 3, 2017

Implemented PruneableInterface on TagAwareAdapter symfony/symfony#24075

Closed

robfrawley force-pushed the feature-document-cache-pruneable-additions branch 2 times, most recently from 3067a34 to adb411e Compare September 5, 2017 05:41

robfrawley force-pushed the feature-document-cache-pruneable-additions branch from adb411e to b2e2710 Compare January 22, 2018 23:33

robfrawley force-pushed the feature-document-cache-pruneable-additions branch from b2e2710 to ea29252 Compare January 22, 2018 23:50

javiereguiluz added Status: Reviewed and removed Status: Needs Review labels Jan 23, 2018

javiereguiluz added 4 commits January 23, 2018 08:33

Wrapped long lines

eb70a36

Fixed a typo

5bea1e6

Typos and wrapped long lines

1322ffd

Typo

54a1e62

javiereguiluz merged commit 54a1e62 into symfony:3.4 Jan 23, 2018

xabbuh added a commit that referenced this pull request Jan 23, 2018

[#8209] fix reference

049096c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command #8209

[Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command #8209

robfrawley commented Jul 22, 2017 •

edited

robfrawley Aug 14, 2017 •

edited

robfrawley Aug 14, 2017

robfrawley commented Aug 31, 2017 •

edited

Toflar commented Sep 3, 2017

robfrawley commented Sep 4, 2017 •

edited

Toflar commented Sep 4, 2017

robfrawley commented Sep 5, 2017

robfrawley commented Jan 22, 2018

robfrawley commented Jan 22, 2018

javiereguiluz commented Jan 23, 2018

robfrawley commented Jan 23, 2018

[Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command #8209

[Cache] Document (filesystem|phpfiles|pdo|chain) cache (adapter|simple) prune method and prune command #8209

Conversation

robfrawley commented Jul 22, 2017 • edited

robfrawley Aug 14, 2017 • edited

Choose a reason for hiding this comment

robfrawley Aug 14, 2017

Choose a reason for hiding this comment

robfrawley commented Aug 31, 2017 • edited

Toflar commented Sep 3, 2017

robfrawley commented Sep 4, 2017 • edited

Toflar commented Sep 4, 2017

robfrawley commented Sep 5, 2017

robfrawley commented Jan 22, 2018

robfrawley commented Jan 22, 2018

javiereguiluz commented Jan 23, 2018

robfrawley commented Jan 23, 2018

robfrawley commented Jul 22, 2017 •

edited

robfrawley Aug 14, 2017 •

edited

robfrawley commented Aug 31, 2017 •

edited

robfrawley commented Sep 4, 2017 •

edited