Merge branch '2.7' into 2.8

_theme/_templates/layout.html

@@ -44,9 +44,9 @@
         <div id="sidebar" class="col-sm-3">
             <div id="sidebar-content">
                 <div id="demo-warning">
-                    <h4>This is a demo</h4>
-                    <p>This is a demo provided by platform.sh.<br>
-                    <a href="http://symfony.com/doc/current/{{ pagename }}">Visit on symfony.com</a>.</p>
+                    <h4>Pull request build</h4>
+                    <p>Each pull request of the Symfony Documentation is automatically deployed and hosted on <a href="https://platform.sh">Platform.sh</a>.<br>
+                    Visit the page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
                 </div>
 
                 {%- include "globaltoc.html" %}

book/http_cache.rst

@@ -230,7 +230,7 @@ Here is a list of the main options:
 ``allow_revalidate``
     Specifies whether the client can force a cache revalidate by including a
     ``Cache-Control`` "max-age=0" directive in the request. Set it to ``true`` for
-    compliance with RFC 2616 (default: false).
+    compliance with RFC 2616 (default: ``false``).
 
 ``stale_while_revalidate``
     Specifies the default number of seconds (the granularity is the second as the
@@ -882,8 +882,8 @@ that data from its cache.
 
     If you want to use cache invalidation, have a look at the
     `FOSHttpCacheBundle`_. This bundle provides services to help with various
-    cache invalidation concepts, and also documents the configuration for the
-    a couple of common caching proxies.
+    cache invalidation concepts and also documents the configuration for a
+    couple of common caching proxies.
 
 If one content corresponds to one URL, the ``PURGE`` model works well.
 You send a request to the cache proxy with the HTTP method ``PURGE`` (using

book/security.rst

@@ -512,7 +512,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
 
 .. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
 
-Of course, your user's passwords now need to be encoded with this exact algorithm.
+Of course, your users' passwords now need to be encoded with this exact algorithm.
 For hardcoded users, you can use an `online tool`_, which will give you something
 like this:
 

book/translation.rst

@@ -593,7 +593,7 @@ use somewhere in your application::
         public $name;
     }
 
-Add constraints though any of the supported methods. Set the message option to the
+Add constraints through any of the supported methods. Set the message option to the
 translation source text. For example, to guarantee that the ``$name`` property is
 not empty, add the following:
 

book/validation.rst

@@ -734,19 +734,19 @@ user registers and when a user updates their contact information later:
         class User implements UserInterface
         {
             /**
-            * @Assert\Email(groups={"registration"})
-            */
+             * @Assert\Email(groups={"registration"})
+             */
             private $email;
 
             /**
-            * @Assert\NotBlank(groups={"registration"})
-            * @Assert\Length(min=7, groups={"registration"})
-            */
+             * @Assert\NotBlank(groups={"registration"})
+             * @Assert\Length(min=7, groups={"registration"})
+             */
             private $password;
 
             /**
-            * @Assert\Length(min=2)
-            */
+             * @Assert\Length(min=2)
+             */
             private $city;
         }
 
@@ -927,13 +927,13 @@ username and the password are different only if all other validation passes
         class User implements UserInterface
         {
             /**
-            * @Assert\NotBlank
-            */
+             * @Assert\NotBlank
+             */
             private $username;
 
             /**
-            * @Assert\NotBlank
-            */
+             * @Assert\NotBlank
+             */
             private $password;
 
             /**

components/dependency_injection/synthetic_services.rst

@@ -27,7 +27,7 @@ service is injected into the container from within the ``Kernel`` class::
 The ``kernel`` service is called a synthetic service. This service has to
 be configured in the container, so the container knows the service does
 exist during compilation (otherwise, services depending on this ``kernel``
-service will get a "service does not exists" error).
+service will get a "service does not exist" error).
 
 In order to do so, you have to use
 :method:`Definition::setSynthetic() <Symfony\\Component\\DependencyInjection\\Definition::setSynthetic>`::

components/http_foundation/introduction.rst

@@ -464,8 +464,8 @@ represented by a PHP callable instead of a string::
     you must call ``ob_flush()`` before ``flush()``.
 
     Additionally, PHP isn't the only layer that can buffer output. Your web
-    server might also buffer based on its configuration. Even more, if you
-    use fastcgi, buffering can't be disabled at all.
+    server might also buffer based on its configuration. What's more, if you
+    use FastCGI, buffering can't be disabled at all.
 
 .. _component-http-foundation-serving-files:
 

components/routing/introduction.rst

@@ -39,7 +39,7 @@ your autoloader to load the Routing component::
     $routes = new RouteCollection();
     $routes->add('route_name', $route);
 
-    $context = new RequestContext($_SERVER['REQUEST_URI']);
+    $context = new RequestContext('/');
 
     $matcher = new UrlMatcher($routes, $context);
 
@@ -203,7 +203,7 @@ a certain route::
     $routes = new RouteCollection();
     $routes->add('show_post', new Route('/show/{slug}'));
 
-    $context = new RequestContext($_SERVER['REQUEST_URI']);
+    $context = new RequestContext('/');
 
     $generator = new UrlGenerator($routes, $context);
 
@@ -323,7 +323,7 @@ automatically in the background if you want to use it. A basic example of the
 :class:`Symfony\\Component\\Routing\\Router` class would look like::
 
     $locator = new FileLocator(array(__DIR__));
-    $requestContext = new RequestContext($_SERVER['REQUEST_URI']);
+    $requestContext = new RequestContext('/');
 
     $router = new Router(
         new YamlFileLoader($locator),

contributing/code/standards.rst

@@ -37,6 +37,9 @@ example containing most features described below:
     {
         const SOME_CONST = 42;
 
+        /**
+         * @var string
+         */
         private $fooBar;
 
         /**
@@ -48,20 +51,30 @@ example containing most features described below:
         }
 
         /**
-         * @param string $dummy Some argument description
-         * @param array  $options
+         * Transforms the input given as first argument.
+         *
+         * @param bool|string $dummy   Some argument description
+         * @param array       $options An options collection to be used within the transformation
          *
-         * @return string|null Transformed input
+         * @return string|null The transformed input
          *
-         * @throws \RuntimeException
+         * @throws \RuntimeException When an invalid option is provided
          */
         private function transformText($dummy, array $options = array())
         {
+            $defaultOptions = array(
+                'some_default' => 'values',
+                'another_default' => 'more values',
+            );
+
+            foreach ($options as $option) {
+                if (!in_array($option, $defaultOptions)) {
+                    throw new \RuntimeException(sprintf('Unrecognized option "%s"', $option));
+                }
+            }
+
             $mergedOptions = array_merge(
-                array(
-                    'some_default' => 'values',
-                    'another_default' => 'more values',
-                ),
+                $defaultOptions,
                 $options
             );
 
@@ -76,10 +89,16 @@ example containing most features described below:
 
                 return ucwords($dummy);
             }
-
-            throw new \RuntimeException(sprintf('Unrecognized dummy option "%s"', $dummy));
         }
 
+        /**
+         * Performs some basic check for a given value.
+         *
+         * @param mixed $value     Some value to check against
+         * @param bool  $theSwitch Some switch to control the method's flow
+         *
+         * @return bool|null The resultant check if $theSwitch isn't false, null otherwise
+         */
         private function reverseBoolean($value = null, $theSwitch = false)
         {
             if (!$theSwitch) {

contributing/code/tests.rst

@@ -16,14 +16,13 @@ In any case, it's a good practice to run tests locally before submitting a
 Before Running the Tests
 ------------------------
 
-To run the Symfony test suite, `install PHPUnit`_ 4.2 (or later) first. Then,
-install the external dependencies used during the tests, such as Doctrine, Twig
-and Monolog. To do so, :doc:`install Composer </cookbook/composer>` and execute
-the following:
+To run the Symfony test suite, install the external dependencies used during the
+tests, such as Doctrine, Twig and Monolog. To do so,
+:doc:`install Composer </cookbook/composer>` and execute the following:
 
 .. code-block:: bash
 
-    $ composer install
+    $ composer update
 
 .. _running:
 
@@ -35,7 +34,7 @@ command:
 
 .. code-block:: bash
 
-    $ phpunit
+    $ php ./phpunit symfony
 
 The output should display ``OK``. If not, read the reported errors to figure out
 what's going on and if the tests are broken because of the new code.
@@ -48,6 +47,12 @@ what's going on and if the tests are broken because of the new code.
 
     .. code-block:: bash
 
-        $ phpunit src/Symfony/Component/Finder/
+        $ php ./phpunit src/Symfony/Component/Finder/
 
-.. _`install PHPUnit`: https://phpunit.de/manual/current/en/installation.html
+.. tip::
+
+    On Windows, install the `ConEmu`_ or `ANSICON`_ free applications to see
+    colored test results.
+
+.. _ConEmu: https://code.google.com/p/conemu-maximus5/
+.. _ANSICON: https://github.com/adoxa/ansicon/releases

cookbook/cache/varnish.rst

@@ -75,23 +75,43 @@ session cookie, if there is one, and get rid of all other cookies so that pages
 are cached if there is no active session. Unless you changed the default
 configuration of PHP, your session cookie has the name ``PHPSESSID``:
 
-.. code-block:: varnish4
+.. configuration-block::
 
-    sub vcl_recv {
-        // Remove all cookies except the session ID.
-        if (req.http.Cookie) {
-            set req.http.Cookie = ";" + req.http.Cookie;
-            set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
-            set req.http.Cookie = regsuball(req.http.Cookie, ";(PHPSESSID)=", "; \1=");
-            set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
-            set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
-
-            if (req.http.Cookie == "") {
-                // If there are no more cookies, remove the header to get page cached.
-                remove req.http.Cookie;
+    .. code-block:: varnish4
+
+        sub vcl_recv {
+            // Remove all cookies except the session ID.
+            if (req.http.Cookie) {
+                set req.http.Cookie = ";" + req.http.Cookie;
+                set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
+                set req.http.Cookie = regsuball(req.http.Cookie, ";(PHPSESSID)=", "; \1=");
+                set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
+                set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
+    
+                if (req.http.Cookie == "") {
+                    // If there are no more cookies, remove the header to get page cached.
+                    unset req.http.Cookie;
+                }
+            }
+        }
+
+    .. code-block:: varnish3
+
+        sub vcl_recv {
+            // Remove all cookies except the session ID.
+            if (req.http.Cookie) {
+                set req.http.Cookie = ";" + req.http.Cookie;
+                set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
+                set req.http.Cookie = regsuball(req.http.Cookie, ";(PHPSESSID)=", "; \1=");
+                set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
+                set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
+    
+                if (req.http.Cookie == "") {
+                    // If there are no more cookies, remove the header to get page cached.
+                    remove req.http.Cookie;
+                }
             }
         }
-    }
 
 .. tip::