Merge branch '2.3' into 2.7

Conflicts:	cookbook/security/voters.rst	reference/dic_tags.rst

Author: xabbuh

_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