Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

_build/_theme/_templates/layout.html

@@ -1,13 +1,13 @@
 {% extends '!layout.html' %}
 
-{% set css_files = ['http://symfony.com/css/compiled/v5/all.css?v=4'] %}
+{% set css_files = ['https://symfony.com/css/compiled/v5/all.css?v=4'] %}
 {# make sure the Sphinx stylesheet isn't loaded #}
 {% set style = '' %}
 {% set isIndex = pagename is index %}
 
 {% block extrahead %}
 {# add JS to support tabs #}
-<script src="http://symfony.com/js/v5/all.js?v=4"></script>
+<script src="https://symfony.com/js/v5/all.js?v=4"></script>
 
 {# pygment's styles are still loaded, undo some unwanted styles #}
 <style>
@@ -48,7 +48,7 @@ <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>
                     View this page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
                 </div>
-                
+
                 {%- include "globaltoc.html" %}
 
                 {% if not isIndex %}
@@ -81,7 +81,7 @@ <h1 class="content_title">{{ title }}</h1>
                 <a href="{{ next.link|e }}">{{ next.title|striptags|e }} »</a>
             </div>
             {% endif %}
-            
+
             <div id="license">
                 <p>This work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">License</a>.</p>
             </div>

_images/doctrine/doctrine_web_debug_toolbar.png

@@ -235,16 +235,15 @@ more advanced use-case, you can always do the same security check in PHP:
 
         if (!$post->isAuthor($this->getUser())) {
             $this->denyAccessUnlessGranted('edit', $post);
-
-	    // or without the shortcut:
-	    //
-	    // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-	    // ...
-	    //
-	    // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
-	    //    throw $this->createAccessDeniedException();
-	    // }
         }
+        // equivalent code without using the "denyAccessUnlessGranted()" shortcut:
+        //
+        // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+        // ...
+        //
+        // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
+        //    throw $this->createAccessDeniedException();
+        // }
 
         // ...
     }
@@ -398,6 +397,6 @@ If your company uses a user login method not supported by Symfony, you can
 develop :doc:`your own user provider </security/custom_provider>` and
 :doc:`your own authentication provider </security/custom_authentication_provider>`.
 
-.. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Security annotation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
+.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

_images/doctrine/web_debug_toolbar.png

@@ -83,7 +83,7 @@ bundle configuration would look like:
         <?xml version="1.0" ?>
 
         <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:acme-social="http://example.org/dic/schema/acme_social"
+            xmlns:acme-social="http://example.org/schema/dic/acme_social"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
@@ -325,7 +325,7 @@ configuration of a specific bundle. The namespace is returned from the
 :method:`Extension::getNamespace() <Symfony\\Component\\DependencyInjection\\Extension\\Extension::getNamespace>`
 method. By convention, the namespace is a URL (it doesn't have to be a valid
 URL nor does it need to exists). By default, the namespace for a bundle is
-``http://example.org/dic/schema/DI_ALIAS``, where ``DI_ALIAS`` is the DI alias of
+``http://example.org/schema/dic/DI_ALIAS``, where ``DI_ALIAS`` is the DI alias of
 the extension. You might want to change this to a more professional URL::
 
     // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php

best_practices/security.rst

@@ -133,6 +133,21 @@ The output will look like this:
         node_paths:           []
         # ...
 
+.. tip::
+
+    For complex bundles that define lots of configuration options, you can pass
+    a second optional argument to the ``config:dump-reference`` command to only
+    display a section of the entire configuration:
+
+    .. code-block:: terminal
+
+        $ bin/console config:dump-reference AsseticBundle use_controller
+
+        # Default configuration for "AsseticBundle" at path "use_controller"
+        use_controller:
+            enabled:              '%kernel.debug%'
+            profiler:             false
+
 Other Setup
 -----------
 

bundles/configuration.rst

@@ -154,14 +154,11 @@ can override the translations from any translation file, as long as it is in
 
 .. caution::
 
-    The last translation file always wins. That means that you need to make
-    sure that the bundle containing *your* translations is loaded after any
+    Translation files are not aware of :doc:`bundle inheritance </bundles/inheritance>`.
+    If you want to override translations from the parent bundle or another bundle,
+    make sure that the bundle containing *your* translations is loaded after any
     bundle whose translations you're overriding. This is done in ``AppKernel``.
 
-    Translation files are also not aware of :doc:`bundle inheritance </bundles/inheritance>`.
-    If you want to override translations from the parent bundle, be sure that the
-    parent bundle is loaded before the child bundle in the ``AppKernel`` class.
-
-    The file that always wins is the one that is placed in
-    ``app/Resources/translations``, as those files are always loaded last.
+    Finally, translations located in ``app/Resources/translations`` will override
+    all the other translations since those files are always loaded last.
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

bundles/installation.rst

@@ -188,7 +188,7 @@ into the client constructor::
     $cookieJar = new Cookie('flavor', 'chocolate', strtotime('+1 day'));
 
     // create a client and set the cookies
-    $client = new Client(array(), array(), $cookieJar);
+    $client = new Client(array(), null, $cookieJar);
     // ...
 
 History

bundles/override.rst

@@ -6,13 +6,17 @@
 The Cache Component
 ===================
 
-    The Cache component provides an extended `PSR-6`_ implementation for adding
-    cache to your applications. It is designed to have a low overhead and it
-    ships with ready to use adapters for the most common caching backends.
+    The Cache component provides an extended `PSR-6`_ implementation as well as
+    a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications.
+    It is designed to have a low overhead and it ships with ready to use adapters
+    for the most common caching backends.
 
 .. versionadded:: 3.1
     The Cache component was introduced in Symfony 3.1.
 
+.. versionadded:: 3.3
+    The PSR-16 "Simple Cache" implementation was introduced in Symfony 3.3.
+
 Installation
 ------------
 
@@ -21,11 +25,113 @@ You can install the component in 2 different ways:
 * :doc:`Install it via Composer </components/using_components>` (``symfony/cache`` on `Packagist`_);
 * Use the official Git repository (https://github.com/symfony/cache).
 
-Key Concepts
-------------
+Cache (PSR-6) Versus Simple Cache (PSR-16)
+------------------------------------------
+
+This component includes *two* different approaches to caching:
+
+:ref:`PSR-6 Caching <cache-component-psr6-caching>`:
+     A fully-featured cache system, which includes cache "pools", more advanced
+     cache "items", and :ref:`cache tagging for invalidation <cache-component-tags>`.
+
+:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
+    A simple way to store, fetch and remove items from a cache.
+
+Both methods support the *same* cache adapters and will give you very similar performance.
+
+.. tip::
+
+    The component also contains adapters to convert between PSR-6 and PSR-16 caches.
+    See :doc:`/components/cache/psr6_psr16_adapters`.
+
+.. _cache-component-psr16-caching:
+
+Simple Caching (PSR-16)
+-----------------------
+
+This part of the component is an implementation of `PSR-16`_, which means that its
+basic API is the same as defined in the standard. First, create a cache object from
+one of the built-in cache classes. For example, to create a filesystem-based cache,
+instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
+
+    use Symfony\Component\Cache\Simple\FilesystemCache;
+
+    $cache = new FilesystemCache();
+
+Now you can create, retrieve, update and delete items using this object::
+
+    // save a new item in the cache
+    $cache->set('stats.num_products', 4711);
+
+    // or set it with a custom ttl
+    // $cache->set('stats.num_products', 4711, 3600);
+
+    // retrieve the cache item
+    if (!$cache->has('stats.num_products')) {
+        // ... item does not exists in the cache
+    }
+
+    // retrieve the value stored by the item
+    $numProducts = $cache->get('stats.num_products');
+
+    // or specify a default value, if the key doesn't exist
+    // $numProducts = $cache->get('stats.num_products', 100);
+
+    // remove the cache key
+    $cache->delete('stats.num_products');
+    
+    // clear *all* cache keys
+    $cache->clear();
+
+You can also work with multiple items at once::
+
+    $cache->setMultiple(array(
+        'stats.num_products' => 4711,
+        'stats.num_users' => 1356,
+    ));
+
+    $stats = $cache->getMultiple(array(
+        'stats.num_products',
+        'stats.num_users',
+    ));
 
-Before starting to use the Cache component, it's important that you learn the
-meaning of some key concepts:
+    $cache->deleteMultiple(array(
+        'stats.num_products',
+        'stats.num_users',
+    ));
+
+Available Simple Cache (PSR-16) Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following cache adapters are available:
+
+.. tip::
+
+    To find out more about each of these classes, you can read the
+    :doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
+    (PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
+    each share constructor arguments and use-cases.
+
+* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
+
+.. _cache-component-psr6-caching:
+
+More Advanced Caching (PSR-6)
+-----------------------------
+
+To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
+concepts:
 
 **Item**
     A single unit of information stored as a key/value pair, where the key is
@@ -37,13 +143,13 @@ meaning of some key concepts:
 **Adapter**
     It implements the actual caching mechanism to store the information in the
     filesystem, in a database, etc. The component provides several ready to use
-    adapters for common caching backends (Redis, APCu, etc.)
+    adapters for common caching backends (Redis, APCu, Doctrine, PDO, etc.)
 
-Basic Usage
------------
+Basic Usage (PSR-6)
+-------------------
 
-This component is an implementation of `PSR-6`_, which means that its basic API
-is the same as defined in the standard. Before starting to cache information,
+This part of the component is an implementation of `PSR-6`_, which means that its
+basic API is the same as defined in the standard. Before starting to cache information,
 create the cache pool using any of the built-in adapters. For example, to create
 a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::
 
@@ -71,8 +177,10 @@ Now you can create, retrieve, update and delete items using this cache pool::
     // remove the cache item
     $cache->deleteItem('stats.num_products');
 
-Advanced Usage
---------------
+For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
+
+Advanced Usage (PSR-6)
+----------------------
 
 .. toctree::
     :glob:
@@ -81,4 +189,5 @@ Advanced Usage
     cache/*
 
 .. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
+.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
 .. _Packagist: https://packagist.org/packages/symfony/cache

components/browser_kit.rst

@@ -7,7 +7,7 @@ Cache Invalidation
 
 Cache invalidation is the process of removing all cached items related to a
 change in the state of your model. The most basic kind of invalidation is direct
-items deletion. But when the state of a primary resource has spread accross
+items deletion. But when the state of a primary resource has spread across
 several cached items, keeping them in sync can be difficult.
 
 The Symfony Cache component provides two mechanisms to help solving this problem: