feature #21038 [FrameworkBundle] deprecated cache:clear with warmup (fabpot)

This PR was merged into the 3.3-dev branch.

Discussion
----------

[FrameworkBundle] deprecated cache:clear with warmup

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | n/a

The warmup part of `cache:clear` does not work well, and does not deliver the guarantee that the generated cache is exactly the same as the one that would have been generated via `cache:warmup`.

As one of the goal of Symfony 4 is to be able to generate all the cache for read-only filsystem, I propose to deprecate the warmup part of `cache:clear` in 3.3 to be able to remove it completely in 4.0. In 4.0, the `--no-warmup` option would be a noop (and can then be removed in 5.0).

Commits
-------

7ed3237645 [FrameworkBundle] deprecated cache:clear with warmup

UPGRADE-3.3.md

@@ -123,6 +123,9 @@ Finder
 FrameworkBundle
 ---------------
 
+ * The `cache:clear` command should always be called with the `--no-warmup` option.
+   Warmup should be done via the `cache:warmup` command.
+
  * The `Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\AddConsoleCommandPass` has been deprecated. Use `Symfony\Component\Console\DependencyInjection\AddConsoleCommandPass` instead.
 
  * The `Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\SerializerPass` class has been

UPGRADE-4.0.md

@@ -124,7 +124,7 @@ EventDispatcher
    Use `EventDispatcher` with closure-proxy injection instead.
 
 ExpressionLanguage
-----------
+------------------
 
  * The ability to pass a `ParserCacheInterface` instance to the `ExpressionLanguage`
    class has been removed. You should use the `CacheItemPoolInterface` interface
@@ -187,6 +187,9 @@ Form
 FrameworkBundle
 ---------------
 
+ * The `cache:clear` command does not warmup the cache anymore. Warmup should
+   be done via the `cache:warmup` command.
+
  * Support for absolute template paths has been removed.
 
  * The following form types registered as services have been removed; use their

src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 3.3.0
 -----
 
+ * Deprecated `cache:clear` with warmup (always call it with `--no-warmup`)
  * Changed default configuration for
    assets/forms/validation/translation/serialization/csrf from `canBeEnabled()` to
    `canBeDisabled()` when Flex is used

src/Symfony/Bundle/FrameworkBundle/Command/CacheClearCommand.php

@@ -54,7 +54,6 @@ EOF
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $outputIsVerbose = $output->isVerbose();
         $io = new SymfonyStyle($input, $output);
 
         $realCacheDir = $this->getContainer()->getParameter('kernel.cache_dir');
@@ -78,47 +77,59 @@ EOF
         if ($input->getOption('no-warmup')) {
             $filesystem->rename($realCacheDir, $oldCacheDir);
         } else {
-            // the warmup cache dir name must have the same length than the real one
-            // to avoid the many problems in serialized resources files
-            $realCacheDir = realpath($realCacheDir);
-            $warmupDir = substr($realCacheDir, 0, -1).('_' === substr($realCacheDir, -1) ? '-' : '_');
+            @trigger_error('Calling cache:clear without the --no-warmup option is deprecated since version 3.3. Cache warmup should be done with the cache:warmup command instead.', E_USER_DEPRECATED);
 
-            if ($filesystem->exists($warmupDir)) {
-                if ($outputIsVerbose) {
-                    $io->comment('Clearing outdated warmup directory...');
-                }
-                $filesystem->remove($warmupDir);
-            }
-
-            if ($outputIsVerbose) {
-                $io->comment('Warming up cache...');
-            }
-            $this->warmup($warmupDir, $realCacheDir, !$input->getOption('no-optional-warmers'));
-
-            $filesystem->rename($realCacheDir, $oldCacheDir);
-            if ('\\' === DIRECTORY_SEPARATOR) {
-                sleep(1);  // workaround for Windows PHP rename bug
-            }
-            $filesystem->rename($warmupDir, $realCacheDir);
+            $this->warmupCache($input, $output, $realCacheDir, $oldCacheDir);
         }
 
-        if ($outputIsVerbose) {
+        if ($output->isVerbose()) {
             $io->comment('Removing old cache directory...');
         }
 
         $filesystem->remove($oldCacheDir);
 
-        if ($outputIsVerbose) {
+        if ($output->isVerbose()) {
             $io->comment('Finished');
         }
 
         $io->success(sprintf('Cache for the "%s" environment (debug=%s) was successfully cleared.', $kernel->getEnvironment(), var_export($kernel->isDebug(), true)));
     }
 
+    private function warmupCache(InputInterface $input, OutputInterface $output, $realCacheDir, $oldCacheDir)
+    {
+        $filesystem = $this->getContainer()->get('filesystem');
+        $io = new SymfonyStyle($input, $output);
+
+        // the warmup cache dir name must have the same length than the real one
+        // to avoid the many problems in serialized resources files
+        $realCacheDir = realpath($realCacheDir);
+        $warmupDir = substr($realCacheDir, 0, -1).('_' === substr($realCacheDir, -1) ? '-' : '_');
+
+        if ($filesystem->exists($warmupDir)) {
+            if ($output->isVerbose()) {
+                $io->comment('Clearing outdated warmup directory...');
+            }
+            $filesystem->remove($warmupDir);
+        }
+
+        if ($output->isVerbose()) {
+            $io->comment('Warming up cache...');
+        }
+        $this->warmup($warmupDir, $realCacheDir, !$input->getOption('no-optional-warmers'));
+
+        $filesystem->rename($realCacheDir, $oldCacheDir);
+        if ('\\' === DIRECTORY_SEPARATOR) {
+            sleep(1);  // workaround for Windows PHP rename bug
+        }
+        $filesystem->rename($warmupDir, $realCacheDir);
+    }
+
     /**
      * @param string $warmupDir
      * @param string $realCacheDir
      * @param bool   $enableOptionalWarmers
+     *
+     * @internal to be removed in 4.0
      */
     protected function warmup($warmupDir, $realCacheDir, $enableOptionalWarmers = true)
     {
@@ -183,6 +194,8 @@ EOF
      * @param string          $warmupDir
      *
      * @return KernelInterface
+     *
+     * @internal to be removed in 4.0
      */
     protected function getTempKernel(KernelInterface $parent, $namespace, $parentClass, $warmupDir)
     {

src/Symfony/Bundle/FrameworkBundle/Tests/Command/CacheClearCommand/CacheClearCommandTest.php

@@ -43,6 +43,9 @@ class CacheClearCommandTest extends TestCase
         $this->fs->remove($this->rootDir);
     }
 
+    /**
+     * @group legacy
+     */
     public function testCacheIsFreshAfterCacheClearedWithWarmup()
     {
         $input = new ArrayInput(array('cache:clear'));