feature symfony#5922 Added minimal cookbook article about the shared flag (WouterJ)

This PR was merged into the 2.8 branch.

Discussion
----------

Added minimal cookbook article about the shared flag

| Q | A
| --- | ---
| Doc fix? | no
| New docs? | yes (symfony/symfony#14984)
| Applies to | 2.8+
| Fixed tickets | symfony#5437

Commits
-------

943ee0c Added minimal cookbook article about shared

Author: weaverryan

Diff for: book/service_container.rst

@@ -145,7 +145,7 @@ As a bonus, the ``Mailer`` service is only created once and the same
 instance is returned each time you ask for the service. This is almost always
 the behavior you'll need (it's more flexible and powerful), but you'll learn
 later how you can configure a service that has multiple instances in the
-":doc:`/cookbook/service_container/scopes`" cookbook article.
+":doc:`/cookbook/service_container/shared`" cookbook article.
 
 .. note::
 

Diff for: cookbook/service_container/index.rst

@@ -4,5 +4,6 @@ Service Container
 .. toctree::
     :maxdepth: 2
 
+    shared
     scopes
     compiler_passes

Diff for: cookbook/service_container/scopes.rst

@@ -8,6 +8,11 @@ How to Work with Scopes
 
     The "container scopes" concept explained in this article has been deprecated
     in Symfony 2.8 and it will be removed in Symfony 3.0.
+    
+    Use the ``request_stack`` service (introduced in Symfony 2.4) instead of
+    the ``request`` service/scope and use the ``shared`` setting (introduced in
+    Symfony 2.8) instead of the ``prototype`` scope
+    (:doc:`read more about shared services </cookbook/service_container/shared>`).
 
 This article is all about scopes, a somewhat advanced topic related to the
 :doc:`/book/service_container`. If you've ever gotten an error mentioning

Diff for: cookbook/service_container/shared.rst

@@ -0,0 +1,43 @@
+.. index::
+    single: Service Container; Shared Services
+
+How to Define Not Shared Services
+=================================
+
+.. versionadded:: 2.8
+    The ``shared`` setting was introduced in Symfony 2.8. Prior to Symfony 2.8,
+    you had to use the ``prototype`` scope.
+
+In the service container, all services are shared by default. This means that
+each time you retrieve the service, you'll get the *same* instance. This is
+often the behaviour you want, but in some cases, you might want to always get a
+*new* instance.
+
+In order to always get a new instance, set the ``shared`` setting to ``false``
+in your service definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            app.some_not_shared_service:
+                class: ...
+                shared: false
+                # ...
+
+    .. code-block:: xml
+
+        <services>
+            <service id="app.some_not_shared_service" class="..." shared="false" />
+        </services>
+
+    .. code-block:: php
+
+        $definition = new Definition('...');
+        $definition->setShared(false);
+
+        $container->setDefinition('app.some_not_shared_service', $definition);
+
+Now, whenever you call ``$container->get('app.some_not_shared_service')`` or
+inject this service, you'll recieve a new instance.