Merge branch '2.4' into 2.5

* 2.4:
  Changes foobar.net in example.com
  [symfony#4081] Tiny tweak
  Update introduction.rst
  documentation for the ClassMapGenerator class
  fix code block
  fix a headline
  improve linking between proxy config sections

Author: weaverryan

book/http_cache.rst

@@ -163,7 +163,7 @@ The caching kernel will immediately act as a reverse proxy - caching responses
 from your application and returning them to the client.
 
 Now that you're using a "proxy", you'll need to configure ``127.0.0.1`` under
-the ``trusted_proxies`` configuration (see :ref:`reference <reference-framework-trusted-proxies>`).
+the ``trusted_proxies`` configuration (see :ref:`the reference <reference-framework-trusted-proxies>`).
 Without this, the client's IP address and a few other things won't report correctly.
 
 .. tip::

book/service_container.rst

@@ -82,7 +82,7 @@ you need it::
     use Acme\HelloBundle\Mailer;
 
     $mailer = new Mailer('sendmail');
-    $mailer->send('ryan@foobar.net', ...);
+    $mailer->send('ryan@example.com', ...);
 
 This is easy enough. The imaginary ``Mailer`` class allows you to configure
 the method used to deliver the email messages (e.g. ``sendmail``, ``smtp``, etc).

components/class_loader/class_map_generator.rst

@@ -0,0 +1,125 @@
+.. index::
+    single: Autoloading; Class Map Generator
+    single: ClassLoader; Class Map Generator
+
+The Class Map Generator
+=======================
+
+Loading a class usually is an easy task given the `PSR-0`_ and `PSR-4`_ standards.
+Thanks to the Symfony ClassLoader component or the autoloading mechanism provided
+by Composer, you don't have to map your class names to actual PHP files manually.
+Nowadays, PHP libraries usually come with autoloading support through Composer.
+
+But from time to time you may have to use a third-party library that comes
+without any autoloading support and therefore forces you to load each class
+manually. For example, imagine a library with the following directory structure:
+
+.. code-block:: text
+
+    library/
+    ├── bar/
+    │   ├── baz/
+    │   │   └── Boo.php
+    │   └── Foo.php
+    └── foo/
+        ├── bar/
+        │   └── Foo.php
+        └── Bar.php
+
+These files contain the following classes:
+
+=========================== ================
+File                        Class name
+=========================== ================
+``library/bar/baz/Boo.php`` ``Acme\Bar\Baz``
+--------------------------- ----------------
+``library/bar/Foo.php``     ``Acme\Bar``
+--------------------------- ----------------
+``library/foo/bar/Foo.php`` ``Acme\Foo\Bar``
+--------------------------- ----------------
+``library/foo/Bar.php``     ``Acme\Foo``
+=========================== ================
+
+To make your life easier, the ClassLoader component comes with a
+:class:`Symfony\\Component\\ClassLoader\\ClassMapGenerator` class that makes
+it possible to create a map of class names to files.
+
+Generating a Class Map
+----------------------
+
+To generate the class map, simply pass the root directory of your class files
+to the :method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::createMap``
+method::
+
+    use Symfony\Component\ClassLoader\ClassMapGenerator;
+
+    print_r(ClassMapGenerator::createMap(__DIR__.'/library'));
+
+Given the files and class from the table above, you should see an output like
+this:
+
+.. code-block:: text
+
+    Array
+    (
+        [Acme\Foo] => /var/www/library/foo/Bar.php
+        [Acme\Foo\Bar] => /var/www/library/foo/bar/Foo.php
+        [Acme\Bar\Baz] => /var/www/library/bar/baz/Boo.php
+        [Acme\Bar] => /var/www/library/bar/Foo.php
+    )
+
+Dumping the Class Map
+---------------------
+
+Writing the class map to the console output is not really sufficient when
+it comes to autoloading. Luckily, the ``ClassMapGenerator`` provides the
+:method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::dump` method
+to save the generated class map to the filesystem::
+
+    use Symfony\Component\ClassLoader\ClassMapGenerator;
+
+    ClassMapGenerator::dump(__DIR__.'/library', __DIR__.'/class_map.php');
+
+This call to ``dump()`` generates the class map and writes it to the ``class_map.php``
+file in the same directory with the following contents::
+
+    <?php return array (
+    'Acme\\Foo' => '/var/www/library/foo/Bar.php',
+    'Acme\\Foo\\Bar' => '/var/www/library/foo/bar/Foo.php',
+    'Acme\\Bar\\Baz' => '/var/www/library/bar/baz/Boo.php',
+    'Acme\\Bar' => '/var/www/library/bar/Foo.php',
+    );
+
+Instead of loading each file manually, you'll only have to register the generated
+class map with, for example, the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader`::
+
+    use Symfony\Component\ClassLoader\MapClassLoader;
+
+    $mapping = include __DIR__.'/class_map.php';
+    $loader = new MapClassLoader($mapping);
+    $loader->register();
+
+    // you can now use the classes:
+    use Acme\Foo;
+
+    $foo = new Foo();
+
+    // ...
+
+.. note::
+
+    The example assumes that you already have autoloading working (e.g.
+    through `Composer`_ or one of the other class loaders from the ClassLoader
+    component.
+
+Besides dumping the class map for one directory, you can also pass an array
+of directories for which to generate the class map (the result actually is
+the same as in the example above)::
+
+    use Symfony\Component\ClassLoader\ClassMapGenerator;
+
+    ClassMapGenerator::dump(array(__DIR__.'/library/bar', __DIR__.'/library/foo'), __DIR__.'/class_map.php');
+
+.. _`PSR-0`: http://www.php-fig.org/psr/psr-0
+.. _`PSR-4`: http://www.php-fig.org/psr/psr-4
+.. _`Composer`: http://getcomposer.org

components/class_loader/index.rst

@@ -3,10 +3,11 @@ ClassLoader
 
 .. toctree::
     :maxdepth: 2
-    
+
     introduction
     class_loader
     psr4_class_loader
     map_class_loader
     cache_class_loader
     debug_class_loader
+    class_map_generator

components/console/introduction.rst

@@ -461,7 +461,7 @@ method::
             $command = $application->find('demo:greet');
             $commandTester = new CommandTester($command);
             $commandTester->execute(
-                array('command' => $command->getName(), 'name' => 'Fabien')
+                array('command' => $command->getName(), 'name' => 'Fabien', '--iterations' => 5)
             );
 
             $this->assertRegExp('/Fabien/', $commandTester->getDisplay());

components/map.rst.inc

@@ -8,6 +8,7 @@
   * :doc:`/components/class_loader/map_class_loader`
   * :doc:`/components/class_loader/cache_class_loader`
   * :doc:`/components/class_loader/debug_class_loader`
+  * :doc:`/components/class_loader/class_map_generator`
 
 * :doc:`/components/config/index`
 

cookbook/request/load_balancer_reverse_proxy.rst

@@ -1,5 +1,5 @@
-How to Configure Symfony to Work behind a Load Balancer or Reverse Proxy
-========================================================================
+How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy
+==========================================================================
 
 When you deploy your application, you may be behind a load balancer (e.g.
 an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for
@@ -60,7 +60,8 @@ and which reverse proxy IP addresses will be doing this type of thing:
 
 In this example, you're saying that your reverse proxy (or proxies) has
 the IP address ``192.0.0.1`` or matches the range of IP addresses that use
-the CIDR notation ``10.0.0.0/8``. For more details, see :ref:`reference-framework-trusted-proxies`.
+the CIDR notation ``10.0.0.0/8``. For more details, see the
+:ref:`framework.trusted_proxies <reference-framework-trusted-proxies>` option.
 
 That's it! Symfony will now look for the correct ``X-Forwarded-*`` headers
 to get information like the client's IP address, host, port and whether or
@@ -80,13 +81,13 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
    proxies, configure Symfony to *always* trust incoming request. This is
    done inside of your front controller::
 
-    // web/app.php
-    // ...
+       // web/app.php
 
-    Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
+       // ...
+       Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
 
-    $response = $kernel->handle($request);
-    // ...
+       $response = $kernel->handle($request);
+       // ...
 
 That's it! It's critical that you prevent traffic from all non-trusted sources.
 If you allow outside traffic, they could "spoof" their true IP address and
@@ -97,7 +98,7 @@ My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
 
 Most reverse proxies store information on specific ``X-Forwarded-*`` headers.
 But if your reverse proxy uses non-standard header names, you can configure
-these (:doc:`see reference </components/http_foundation/trusting_proxies>`.
+these (see ":doc:`/components/http_foundation/trusting_proxies`").
 The code for doing this will need to live in your front controller (e.g. ``web/app.php``).
 
 .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html