…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

…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

…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

…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

…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