Merge branch '4.4' into 5.1

* 4.4:
  spotted minor EN mistakes and coherence issues between the different …
  Enhancement: Private member variables in code example
  Add warning on Docker integration
  [Cache] Adds mention of using FileSystemTagAwareAdatpter
  Update http_client.rst

Author: javiereguiluz

components/cache/adapters/filesystem_adapter.rst

@@ -55,5 +55,22 @@ and cache root path as constructor parameters::
     :ref:`pruning of expired cache items <component-cache-cache-pool-prune>` by
     calling its ``prune()`` method.
 
+
+.. _filesystem-tag-aware-adapter:
+
+Working with Tags
+-----------------
+
+In order to use tag-based invalidation, you can wrap your adapter in
+:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`, but it's often
+more interesting to use the dedicated :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemTagAwareAdapter`.
+Since tag invalidation logic is implemented using links on filesystem, this
+adapter offers better read performance when using tag-based invalidation::
+
+    use Symfony\Component\Cache\Adapter\FilesystemTagAwareAdapter;
+
+    $cache = new FilesystemTagAwareAdapter();
+
+
 .. _`tmpfs`: https://wiki.archlinux.org/index.php/tmpfs
 .. _`RAM disk solutions`: https://en.wikipedia.org/wiki/List_of_RAM_drive_software

components/cache/cache_invalidation.rst

@@ -61,7 +61,8 @@ method.
 .. note::
 
     When using a Redis backend, consider using :ref:`RedisTagAwareAdapter <redis-tag-aware-adapter>`
-    which is optimized for this purpose.
+    which is optimized for this purpose. When using filesystem, likewise consider to use
+    :ref:`FilesystemTagAwareAdapter <filesystem-tag-aware-adapter>`.
 
 The :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class implements
 instantaneous invalidation (time complexity is ``O(N)`` where ``N`` is the number

create_framework/dependency_injection.rst

@@ -205,7 +205,7 @@ Now, here is how you can register a custom listener in the front controller::
         ->addMethodCall('addSubscriber', [new Reference('listener.string_response')])
     ;
 
-Beside describing your objects, the dependency injection container can also be
+Besides describing your objects, the dependency injection container can also be
 configured via parameters. Let's create one that defines if we are in debug
 mode or not::
 

create_framework/event_dispatcher.rst

@@ -23,7 +23,7 @@ version of this pattern:
 How does it work? The *dispatcher*, the central object of the event dispatcher
 system, notifies *listeners* of an *event* dispatched to it. Put another way:
 your code dispatches an event to the dispatcher, the dispatcher notifies all
-registered listeners for the event, and each listener do whatever it wants
+registered listeners for the event, and each listener does whatever it wants
 with the event.
 
 As an example, let's create a listener that transparently adds the Google

create_framework/front_controller.rst

@@ -132,7 +132,7 @@ its sub-directories (only if needed -- see above tip).
     like ``$request = Request::create('/hello?name=Fabien');`` where the
     argument is the URL path you want to simulate.
 
-Now that the web server always access the same script (``front.php``) for all
+Now that the web server always accesses the same script (``front.php``) for all
 pages, we can secure the code further by moving all other PHP files outside the
 web root directory:
 

create_framework/http_foundation.rst

@@ -273,7 +273,7 @@ cases by yourself. Why not using a technology that already works?
     a look at the ``Symfony\Component\HttpFoundation`` API or read
     its dedicated :doc:`documentation </components/http_foundation>`.
 
-Believe or not but we have our first framework. You can stop now if you want.
+Believe it or not but we have our first framework. You can stop now if you want.
 Using just the Symfony HttpFoundation component already allows you to write
 better and more testable code. It also allows you to write code faster as many
 day-to-day problems have already been solved for you.
@@ -282,7 +282,7 @@ As a matter of fact, projects like Drupal have adopted the HttpFoundation
 component; if it works for them, it will probably work for you. Don't reinvent
 the wheel.
 
-I've almost forgot to talk about one added benefit: using the HttpFoundation
+I've almost forgotten to talk about one added benefit: using the HttpFoundation
 component is the start of better interoperability between all frameworks and
 `applications using it`_ (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `Laravel`_
 and `ezPublish 5`_,  and `more`_).

create_framework/http_kernel_controller_resolver.rst

@@ -31,7 +31,7 @@ The move is pretty straightforward and makes a lot of sense as soon as you
 create more pages but you might have noticed a non-desirable side effect...
 The ``LeapYearController`` class is *always* instantiated, even if the
 requested URL does not match the ``leap_year`` route. This is bad for one main
-reason: performance wise, all controllers for all routes must now be
+reason: performance-wise, all controllers for all routes must now be
 instantiated for every request. It would be better if controllers were
 lazy-loaded so that only the controller associated with the matched route is
 instantiated.

create_framework/http_kernel_httpkernelinterface.rst

@@ -46,8 +46,8 @@ Update your framework so that it implements this interface::
         }
     }
 
-Even if this change looks not too complex, it brings us a lot! Let's talk about one of
-the most impressive one: transparent :doc:`HTTP caching </http_cache>` support.
+With this change, a little goes a long way! Let's talk about one of
+the most impressive upsides: transparent :doc:`HTTP caching </http_cache>` support.
 
 The ``HttpCache`` class implements a fully-featured reverse proxy, written in
 PHP; it implements ``HttpKernelInterface`` and wraps another
@@ -64,7 +64,8 @@ PHP; it implements ``HttpKernelInterface`` and wraps another
         new HttpKernel\HttpCache\Store(__DIR__.'/../cache')
     );
 
-    $framework->handle($request)->send();
+    $response = $framework->handle($request);
+    $response->send();
 
 That's all it takes to add HTTP caching support to our framework. Isn't it
 amazing?

create_framework/separation_of_concerns.rst

@@ -27,9 +27,9 @@ request handling logic into its own ``Simplex\Framework`` class::
 
     class Framework
     {
-        protected $matcher;
-        protected $controllerResolver;
-        protected $argumentResolver;
+        private $matcher;
+        private $controllerResolver;
+        private $argumentResolver;
 
         public function __construct(UrlMatcher $matcher, ControllerResolver $controllerResolver, ArgumentResolver $argumentResolver)
         {

http_client.rst

@@ -629,6 +629,11 @@ when the streams are large)::
         'body' => $formData->bodyToString(),
     ]);
 
+If you need to add a custom HTTP header to the upload, you can do::
+
+    $headers = $formData->getPreparedHeaders()->toArray();
+    $headers[] = 'X-Foo: bar';
+
 Cookies
 ~~~~~~~
 

setup/symfony_server.rst

@@ -378,6 +378,16 @@ its location, same as for ``docker-compose``:
     If you have more than one Docker Compose file, you can provide them all
     separated by ``:`` as explained in the `Docker compose CLI env var reference`_.
 
+.. caution::
+
+    When using Symfony binary with ``php bin/console`` (``symfony console ...``)
+    the binay will **always** use environment variables detected via Docker and will
+    ignore local environment variables.
+    For example if you set up a different database name in your ``.env.test`` file
+    (``DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/test``) and if you run
+    ``symfony console doctrine:database:drop --force --env=test`` the command will drop the database
+    defined in your Docker configuration and not the "test" one.
+
 SymfonyCloud Integration
 ------------------------