Deprecate caching related functionality (#1011)

* Deprecate caching related functionality * fix cs
sonata-project · Mar 7, 2022 · 9d936a6 · 9d936a6
1 parent f2eecc2
commit 9d936a6
Show file tree

Hide file tree

Showing 20 changed files with 419 additions and 29 deletions.
diff --git a/UPGRADE-4.x.md b/UPGRADE-4.x.md
@@ -1,7 +1,20 @@
 UPGRADE 4.x
 ===========
 
-UPGRADE FROM 4.7 to 4.x
+UPGRADE FROM 4.10 to 4.x
+=======================
+
+### Deprecated caching functionality
+
+- The `Sonata\BlockBundle\Cache\HttpCacheHandlerInterface` interface and it's implementations have been deprecated
+- The integration with `SonataCacheBundle` has been deprecated
+
+To get rid of reported deprecations and to prepare your projects for version 5.0 you need to
+- remove dependency on `SonataCacheBundle` if you have it installed
+- set configuration option `sonata_block.http_cache` to `false`
+- remove all other caching related configuration
+
+UPGRADE FROM 4.7 to 4.8
 =======================
 
 ### `sonata-project/doctrine-extensions` is optional

diff --git a/composer.json b/composer.json
@@ -79,6 +79,10 @@
         }
     },
     "config": {
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true,
+            "phpstan/extension-installer": true
+        },
         "sort-packages": true
     },
     "extra": {

diff --git a/src/Block/BlockContextManager.php b/src/Block/BlockContextManager.php
@@ -123,6 +123,7 @@ public function get($meta, array $settings = []): BlockContextInterface
 
         $blockContext = new BlockContext($block, $settings);
 
+        // NEXT_MAJOR: remove next line
         $this->setDefaultExtraCacheKeys($blockContext, $originalSettings);
 
         return $blockContext;
@@ -132,17 +133,23 @@ private function configureSettings(OptionsResolver $optionsResolver, BlockInterf
     {
         // defaults for all blocks
         $optionsResolver->setDefaults([
+            // NEXT_MAJOR: remove
             'use_cache' => true,
+            // NEXT_MAJOR: remove
             'extra_cache_keys' => [],
             'attr' => [],
             'template' => null, // NEXT_MAJOR: Remove the default value
+            // NEXT_MAJOR: remove
             'ttl' => $block->getTtl(),
         ]);
 
         $optionsResolver
+            // NEXT_MAJOR: remove
             ->addAllowedTypes('use_cache', 'bool')
+            // NEXT_MAJOR: remove
             ->addAllowedTypes('extra_cache_keys', 'array')
             ->addAllowedTypes('attr', 'array')
+            // NEXT_MAJOR: remove
             ->addAllowedTypes('ttl', 'int')
             // NEXT_MAJOR: Remove bool and null.
             ->addAllowedTypes('template', ['null', 'string', 'bool'])
@@ -159,6 +166,30 @@ static function (Options $options, $value): string {
                         return '';
                     }
                 )
+            )
+            // NEXT_MAJOR: Remove setDeprecated.
+            ->setDeprecated(
+                'use_cache',
+                ...$this->deprecationParameters(
+                    '4.x',
+                    'Block option "use_cache" is deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.'
+                )
+            )
+            // NEXT_MAJOR: Remove setDeprecated.
+            ->setDeprecated(
+                'extra_cache_keys',
+                ...$this->deprecationParameters(
+                    '4.x',
+                    'Block option "extra_cache_keys" is deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.'
+                )
+            )
+            // NEXT_MAJOR: Remove setDeprecated.
+            ->setDeprecated(
+                'ttl',
+                ...$this->deprecationParameters(
+                    '4.x',
+                    'Block option "ttl" is deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.'
+                )
             );
 
         // add type and class settings for block
@@ -169,6 +200,8 @@ static function (Options $options, $value): string {
     }
 
     /**
+     * // NEXT_MAJOR: remove this method.
+     *
      * Adds context settings, to be able to rebuild a block context, to the
      * extra_cache_keys.
      *

diff --git a/src/Cache/HttpCacheHandler.php b/src/Cache/HttpCacheHandler.php
@@ -17,6 +17,9 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Event\ResponseEvent;
 
+/**
+ * @deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.
+ */
 final class HttpCacheHandler implements HttpCacheHandlerInterface
 {
     /**

diff --git a/src/Cache/HttpCacheHandlerInterface.php b/src/Cache/HttpCacheHandlerInterface.php
@@ -17,6 +17,9 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Event\ResponseEvent;
 
+/**
+ * @deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.
+ */
 interface HttpCacheHandlerInterface
 {
     /**

diff --git a/src/Cache/NoopHttpCacheHandler.php b/src/Cache/NoopHttpCacheHandler.php
@@ -17,6 +17,9 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Event\ResponseEvent;
 
+/**
+ * @deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.
+ */
 final class NoopHttpCacheHandler implements HttpCacheHandlerInterface
 {
     public function alterResponse(Response $response): void

diff --git a/src/DependencyInjection/Compiler/BlockHelperCompilerPass.php b/src/DependencyInjection/Compiler/BlockHelperCompilerPass.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\BlockBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+use Symfony\Component\DependencyInjection\Parameter;
+use Symfony\Component\DependencyInjection\Reference;
+
+/**
+ * @internal
+ *
+ * NEXT_MAJOR: remove this class
+ */
+final class BlockHelperCompilerPass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container): void
+    {
+        /** @var array{by_class: array<class-string, string>, by_type: array<string, string>} $cacheBlocks */
+        $cacheBlocks = $container->getParameter('sonata_block.cache_blocks');
+
+        $hasCacheBlocks = false;
+        foreach ($cacheBlocks as $blocks) {
+            foreach ($blocks as $cacheType) {
+                $hasCacheBlocks = $hasCacheBlocks || 'sonata.cache.noop' !== $cacheType;
+            }
+        }
+
+        if (!$hasCacheBlocks) {
+            return;
+        }
+
+        @trigger_error(
+            'Defining cache blocks other than \'sonata.cache.noop\' is deprecated since sonata-project/block-bundle 4.x and will not be supported anymore in 5.0.',
+            \E_USER_DEPRECATED
+        );
+
+        $blockHelperDefinition = $container->getDefinition('sonata.block.templating.helper');
+        $blockHelperDefinition->setArguments([
+            new Reference('sonata.block.manager'),
+            new Parameter('sonata_block.cache_blocks'),
+            new Reference('sonata.block.renderer'),
+            new Reference('sonata.block.context_manager'),
+            new Reference('event_dispatcher'),
+            new Reference('sonata.cache.manager', ContainerInterface::NULL_ON_INVALID_REFERENCE),
+            new Reference('sonata.block.cache.handler', ContainerInterface::NULL_ON_INVALID_REFERENCE),
+            new Reference('debug.stopwatch', ContainerInterface::NULL_ON_INVALID_REFERENCE),
+        ]);
+    }
+}
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -13,6 +13,7 @@
 
 namespace Sonata\BlockBundle\DependencyInjection;
 
+use Symfony\Component\Config\Definition\BaseNode;
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -29,6 +30,13 @@ final class Configuration implements ConfigurationInterface
      */
     private $defaultContainerTemplates;
 
+    /**
+     * NEXT_MAJOR: remove this member.
+     *
+     * @var bool
+     */
+    private $httpCacheDisabled = false;
+
     /**
      * @param array<string, string> $defaultContainerTemplates
      */
@@ -49,13 +57,23 @@ public function getConfigTreeBuilder(): TreeBuilder
             ->fixXmlConfig('block')
             ->fixXmlConfig('block_by_class')
             ->validate()
-                ->always(static function ($value) {
-                    foreach ($value['blocks'] as $name => &$block) {
+                ->always(function (&$value) {
+                    foreach ($value['blocks'] as &$block) {
                         if (0 === \count($block['contexts'])) {
                             $block['contexts'] = $value['default_contexts'];
                         }
                     }
 
+                    // NEXT_MAJOR: remove this block
+                    if (true !== $this->httpCacheDisabled) {
+                        @trigger_error(
+                            'Not setting the "sonata_block.http_cache" config option to false is deprecated since sonata-project/block-bundle 4.x and will fail in 5.0.',
+                            \E_USER_DEPRECATED
+                        );
+                    } else {
+                        $value['http_cache'] = false;
+                    }
+
                     return $value;
                 })
             ->end()
@@ -73,10 +91,24 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->end()
 
                 ->scalarNode('context_manager')->defaultValue('sonata.block.context_manager.default')->end()
+                // NEXT_MAJOR: deprecate option and only allow setting it to false
                 ->arrayNode('http_cache')
                     ->addDefaultsIfNotSet()
+                    ->beforeNormalization()
+                        ->always(function ($v) {
+                            if (false === $v) {
+                                $this->httpCacheDisabled = true;
+
+                                return [];
+                            }
+
+                            return $v;
+                        })
+                    ->end()
                     ->children()
+                        // NEXT_MAJOR: remove option
                         ->scalarNode('handler')->defaultValue('sonata.block.cache.handler.default')->end()
+                        // NEXT_MAJOR: remove option
                         ->booleanNode('listener')->defaultTrue()->end()
                     ->end()
                 ->end()
@@ -130,7 +162,16 @@ public function getConfigTreeBuilder(): TreeBuilder
                                     ->end()
                                 ->end()
                             ->end()
-                            ->scalarNode('cache')->defaultValue('sonata.cache.noop')->end()
+                            // NEXT_MAJOR: remove cache option
+                            ->scalarNode('cache')
+                                ->defaultValue('sonata.cache.noop')
+                                ->setDeprecated(
+                                    ...$this->getDeprecationMessage(
+                                        'The "cache" option for configuring blocks is deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.',
+                                        '4.x'
+                                    )
+                                )
+                            ->end()
                             ->arrayNode('settings')
                                 ->info('default settings')
                                 ->useAttributeAsKey('id')
@@ -152,7 +193,15 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->prototype('array')
                         ->fixXmlConfig('setting')
                         ->children()
-                            ->scalarNode('cache')->defaultValue('sonata.cache.noop')->end()
+                            ->scalarNode('cache')
+                                ->defaultValue('sonata.cache.noop')
+                                ->setDeprecated(
+                                    ...$this->getDeprecationMessage(
+                                        'The "cache" option for configuring blocks_by_class is deprecated since sonata-project/block-bundle 4.x and will be removed in 5.0.',
+                                        '4.x'
+                                    )
+                                )
+                            ->end()
                             ->arrayNode('settings')
                                 ->info('default settings')
                                 ->useAttributeAsKey('id')
@@ -210,4 +259,21 @@ public function getConfiguration(array $config, ContainerBuilder $container)
     {
         return new self([]);
     }
+
+    /**
+     * @return string[]
+     */
+    private function getDeprecationMessage(string $message, string $version): array
+    {
+        // @phpstan-ignore-next-line
+        if (method_exists(BaseNode::class, 'getDeprecation')) {
+            return [
+                'sonata-project/block-bundle',
+                $version,
+                $message,
+            ];
+        }
+
+        return [$message];
+    }
 }