Merge remote-tracking branch 'origin/2.0' into 2.0

Conflicts:
	components/dependency_injection/introduction.rst

Author: weaverryan

components/dependency_injection/introduction.rst

@@ -279,9 +279,81 @@ The ``newsletter_manager`` and ``mailer`` services can be set up using config fi
         $container->register('newsletter_manager', 'NewsletterManager')
            ->addMethodCall('setMailer', new Reference('mailer');
 
-Learn more about this Component
--------------------------------
+Dumping the Configuration for Performance
+-----------------------------------------
 
-* :doc:`/components/dependency_injection/definitions`
-* :doc:`/components/dependency_injection/factories`
-* :doc:`/components/dependency_injection/parentservices`
+Using configuration files to manage the service container can be much easier
+to understand than using PHP once there are a lot of services. This ease comes
+at a price though when it comes to performance as the config files need to be
+parsed and the PHP configuration built from them. You can have the best of both
+worlds though by using configuration files and then dumping and caching the resulting
+configuration. The ``PhpDumper`` makes dumping the compiled container easy::
+
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\Config\FileLocator;
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+    use Symfony\Component\DependencyInjection\Dumper\PhpDumper
+
+    $container = new ContainerBuilder();
+    $loader = new XmlFileLoader($container, new FileLocator(__DIR__));
+    $loader->load('services.xml');
+
+    $file = __DIR__ .'/cache/container.php';
+
+    if (file_exists($file)) {
+        require_once $file;
+        $container = new ProjectServiceContiner();
+    } else {
+        $container = new ContainerBuilder();
+        $loader = new XmlFileLoader($container, new FileLocator(__DIR__));
+        $loader->load('services.xml');
+
+        $dumper = new PhpDumper($container);
+        file_put_contents($file, $dumper->dump());
+    }
+
+``ProjectServiceContiner`` is the default name given to the dumped container
+class, you can change this though this with the ``class`` option when you dump
+it::
+
+    // ...
+    $file = __DIR__ .'/cache/container.php';
+
+    if (file_exists($file)) {
+        require_once $file;
+        $container = new MyCachedContainer();
+    } else {
+        $container = new ContainerBuilder();
+        $loader = new XmlFileLoader($container, new FileLocator(__DIR__));
+        $loader->load('services.xml');
+
+        $dumper = new PhpDumper($container);
+        file_put_contents($file, $dumper->dump(array('class' => 'MyCachedContainer')));
+    }
+
+You will now get the speed of the PHP configured container with the ease of using
+configuration files. In the above example you will need to delete the cached
+container file whenever you make any changes. Adding a check for a variable that
+determines if you are in debug mode allows you to keep the speed of the cached
+container in production but getting an up to date configuration whilst developing
+your application::
+
+    // ...
+
+    // set $isDebug based on something in your project
+
+    $file = __DIR__ .'/cache/container.php';
+
+    if (!$isDebug && file_exists($file)) {
+        require_once $file;
+        $container = new MyCachedContainer();
+    } else {
+        $container = new ContainerBuilder();
+        $loader = new XmlFileLoader($container, new FileLocator(__DIR__));
+        $loader->load('services.xml');
+
+        if(!$isDebug) {
+   	     $dumper = new PhpDumper($container);
+            file_put_contents($file, $dumper->dump(array('class' => 'MyCachedContainer')));
+        }
+    }