feature #14178 [Config] Delegate creation of ConfigCache instances to…

… a factory. (mpdude)

This PR was squashed before being merged into the 2.7 branch (closes #14178).

Discussion
----------

[Config] Delegate creation of ConfigCache instances to a factory.

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes (refactoring, new flex point)
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | we'll see :-)
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | symfony/symfony-docs#5136

In the Routing/Router and Translation/Translator, delegate creation of ConfigCache instances to a factory. The factory can be setter-injected but will default to a BC implementation.

The ```ConfigCacheFactoryInterface``` is designed in a way that captures the common ```$cache = new ...; if (!$cache->isFresh()) { ... do sth }``` pattern. But more importantly, this design allows factory implementations to take additional measures to avoid race conditions before actually filling the cache.

By using an exchangeable ConfigCache factory it becomes possible to implement different resource (freshness) checking strategies, especially service-based ones.

The goal is to be able to validate Translators and Routers generated by database-based loaders. It might also help with symfony/AsseticBundle#168. This PR only contains the minimum changes needed, so the rest could be implemented in a bundle outside the core (at least for the beginning).

Component/HttpKernel/Kernel::initializeContainer still uses the ConfigCache implementation directly as there is no sensible way of getting/injecting a factory service (chicken-egg).

This is a pick off #7230. It replaces #7781 which was against the master branch. Also see #7781 for additional comments/explanations.

## Todo

* [ ] Allow `symfony/config` `~3.0.0` in `composer.json` for the HttpKernel and Translator component as well as TwigBundle once this PR has been merged into the master branch (fail deps=high tests for the time being).

Commits
-------

6fbe9b1 [Config] Delegate creation of ConfigCache instances to a factory.

UPGRADE-2.7.md

@@ -16,6 +16,12 @@ Router
    but in 2.7 you would get an error if `bar` parameter
    doesn't exist or unexpected result otherwise.
 
+ * The `getMatcherDumperInstance()` and `getGeneratorDumperInstance()` methods in the
+   `Symfony\Component\Routing\Router` have been changed from `protected` to `public`.
+   If you override these methods in a subclass, you will need to change your 
+   methods to `public` as well. Note however that this is a temporary change needed for
+   PHP 5.3 compatibility only. It will be reverted in Symfony 3.0.
+
 Form
 ----
 
@@ -515,3 +521,10 @@ PropertyAccess
 
         new UnexpectedTypeException($value, $path, $pathIndex);
    ```
+
+Config
+------
+
+ * The `__toString()` method of the `\Symfony\Component\Config\ConfigCache` is marked as 
+   deprecated in favor of the new `getPath()` method.
+

src/Symfony/Component/Config/CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+2.7.0
+-----
+
+ * added `ConfigCacheInterface`, `ConfigCacheFactoryInterface` and a basic `ConfigCacheFactory`
+   implementation to delegate creation of ConfigCache instances
+
 2.2.0
 -----
 

src/Symfony/Component/Config/ConfigCache.php

@@ -23,14 +23,12 @@
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
-class ConfigCache
+class ConfigCache implements ConfigCacheInterface
 {
     private $debug;
     private $file;
 
     /**
-     * Constructor.
-     *
      * @param string $file  The absolute cache path
      * @param bool   $debug Whether debugging is enabled or not
      */
@@ -44,8 +42,21 @@ public function __construct($file, $debug)
      * Gets the cache file path.
      *
      * @return string The cache file path
+     * @deprecated since 2.7, to be removed in 3.0. Use getPath() instead.
      */
     public function __toString()
+    {
+        trigger_error('ConfigCache::__toString() is deprecated since version 2.7 and will be removed in 3.0. Use the getPath() method instead.', E_USER_DEPRECATED);
+
+        return $this->file;
+    }
+
+    /**
+     * Gets the cache file path.
+     *
+     * @return string The cache file path
+     */
+    public function getPath()
     {
         return $this->file;
     }

src/Symfony/Component/Config/ConfigCacheFactory.php

@@ -0,0 +1,48 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Config;
+
+/**
+ * Basic implementation for ConfigCacheFactoryInterface
+ * that will simply create an instance of ConfigCache.
+ *
+ * @author Matthias Pigulla <mp@webfactory.de>
+ */
+class ConfigCacheFactory implements ConfigCacheFactoryInterface
+{
+    /**
+     * @var bool Debug flag passed to the ConfigCache
+     */
+    private $debug;
+
+    /**
+     * @param bool $debug The debug flag to pass to ConfigCache
+     */
+    public function __construct($debug)
+    {
+        $this->debug = $debug;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function cache($file, $callback)
+    {
+        $cache = new ConfigCache($file, $this->debug);
+
+        if (!$cache->isFresh()) {
+            call_user_func($callback, $cache);
+        }
+
+        return $cache;
+    }
+}

src/Symfony/Component/Config/ConfigCacheFactoryInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Config;
+
+/**
+ * Interface for a ConfigCache factory. This factory creates
+ * an instance of ConfigCacheInterface and initializes the
+ * cache if necessary.
+ *
+ * @author Matthias Pigulla <mp@webfactory.de>
+ */
+interface ConfigCacheFactoryInterface
+{
+    /**
+     * Creates a cache instance and (re-)initializes it if necessary.
+     *
+     * @param  string               $file        The absolute cache file path
+     * @param  callable             $callable    The callable to be executed when the cache needs to be filled (i. e. is not fresh). The cache will be passed as the only parameter to this callback
+     *
+     * @return ConfigCacheInterface $configCache The cache instance
+     */
+    public function cache($file, $callable);
+}

src/Symfony/Component/Config/ConfigCacheInterface.php

@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Config;
+
+use Symfony\Component\Config\Resource\ResourceInterface;
+
+/**
+ * Interface for ConfigCache
+ *
+ * @author Matthias Pigulla <mp@webfactory.de>
+ */
+interface ConfigCacheInterface
+{
+    /**
+     * Gets the cache file path.
+     *
+     * @return string The cache file path
+     */
+    public function getPath();
+
+    /**
+     * Checks if the cache is still fresh.
+     *
+     * This check should take the metadata passed to the write() method into consideration.
+     *
+     * @return bool Whether the cache is still fresh.
+     */
+    public function isFresh();
+
+    /**
+     * Writes the given content into the cache file. Metadata will be stored
+     * independently and can be used to check cache freshness at a later time.
+     *
+     * @param string                   $content  The content to write into the cache
+     * @param ResourceInterface[]|null $metadata An array of ResourceInterface instances
+     *
+     * @throws \RuntimeException When the cache file cannot be written
+     */
+    public function write($content, array $metadata = null);
+}

src/Symfony/Component/Config/Tests/ConfigCacheTest.php

@@ -47,7 +47,7 @@ public function testToString()
     {
         $cache = new ConfigCache($this->cacheFile, true);
 
-        $this->assertSame($this->cacheFile, (string) $cache);
+        $this->assertSame($this->cacheFile, $cache->getPath());
     }
 
     public function testCacheIsNotFreshIfFileDoesNotExist()

src/Symfony/Component/HttpKernel/Kernel.php

@@ -252,7 +252,7 @@ public function getBundle($name, $first = true)
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritdoc}
      *
      * @throws \RuntimeException if a custom resource is hidden by a resource in a derived bundle
      */
@@ -546,7 +546,7 @@ protected function initializeContainer()
             $fresh = false;
         }
 
-        require_once $cache;
+        require_once $cache->getPath();
 
         $this->container = new $class();
         $this->container->set('kernel', $this);
@@ -695,7 +695,7 @@ protected function dumpContainer(ConfigCache $cache, ContainerBuilder $container
             $dumper->setProxyDumper(new ProxyDumper());
         }
 
-        $content = $dumper->dump(array('class' => $class, 'base_class' => $baseClass, 'file' => (string) $cache));
+        $content = $dumper->dump(array('class' => $class, 'base_class' => $baseClass, 'file' => $cache->getPath()));
         if (!$this->debug) {
             $content = static::stripComments($content);
         }

src/Symfony/Component/HttpKernel/composer.json

@@ -26,7 +26,7 @@
         "symfony/phpunit-bridge": "~2.7|~3.0.0",
         "symfony/browser-kit": "~2.3|~3.0.0",
         "symfony/class-loader": "~2.1|~3.0.0",
-        "symfony/config": "~2.0,>=2.0.5|~3.0.0",
+        "symfony/config": "~2.7",
         "symfony/console": "~2.3|~3.0.0",
         "symfony/css-selector": "~2.0,>=2.0.5|~3.0.0",
         "symfony/dependency-injection": "~2.2|~3.0.0",
@@ -40,6 +40,9 @@
         "symfony/translation": "~2.0,>=2.0.5|~3.0.0",
         "symfony/var-dumper": "~2.6|~3.0.0"
     },
+    "conflict": {
+        "symfony/config": "<2.7"
+    },
     "suggest": {
         "symfony/browser-kit": "",
         "symfony/class-loader": "",