Merge branch '2.3' into 2.6

* 2.3:
  [#5373] Small tweak per Stof's comment
  Fixed a minor grammar issue
  Fixed typos
  Link to the official repository of the bundle.
  Added mentions to some popular (and useful) Symfony bundles
  [#5095] Fixing a typo and updating to a more realistic example
  [#4228] Move synthetic services to its own recipe
  clarify bundle installation instructions
  Implemented the suggestions made by Christian and Wouter
  Replace phpDocumentor by the standard PHPDoc
  Implemented the changes suggested by reviewers
  Fixed an internal link reference
  Reviewed the Bundles cookbook articles
  Constraints - empty strings and null values
  Add a caution to the getUploadRootDir - correction
  Adding a caution to the getUploadRootDir() method
  [#4228] Moved requiring files to definitions

Author: weaverryan

book/security.rst

@@ -280,6 +280,11 @@ But who can you login as? Where do users come from?
     What other methods are supported? See the :doc:`Configuration Reference </reference/configuration/security>`
     or :doc:`build your own </cookbook/security/custom_authentication_provider>`.
 
+.. tip::
+
+    If your application logs users in via a third-party service such as Google,
+    Facebook or Twitter, check out the `HWIOAuthBundle`_ community bundle.
+
 .. _security-user-providers:
 .. _where-do-users-come-from-user-providers:
 
@@ -485,7 +490,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
                 <encoder class="Symfony\Component\Security\Core\User\User"
                     algorithm="bcrypt"
                     cost="12" />
-                
+
                 <!-- ... -->
             </config>
         </srv:container>
@@ -1386,3 +1391,4 @@ Learn More from the Cookbook
 .. _`online tool`: https://www.dailycred.com/blog/12/bcrypt-calculator
 .. _`frameworkextrabundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
+.. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle

components/dependency_injection/advanced.rst

@@ -73,61 +73,6 @@ below) to access this service (via the alias).
 
    Services are by default public.
 
-Synthetic Services
-------------------
-
-Synthetic services are services that are injected into the container instead
-of being created by the container.
-
-For example, if you're using the :doc:`HttpKernel </components/http_kernel/introduction>`
-component with the DependencyInjection component, then the ``request``
-service is injected in the
-:method:`ContainerAwareHttpKernel::handle() <Symfony\\Component\\HttpKernel\\DependencyInjection\\ContainerAwareHttpKernel::handle>`
-method when entering the request :doc:`scope </cookbook/service_container/scopes>`.
-The class does not exist when there is no request, so it can't be included in
-the container configuration. Also, the service should be different for every
-subrequest in the application.
-
-To create a synthetic service, set ``synthetic`` to ``true``:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        services:
-            request:
-                synthetic: true
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <service id="request" synthetic="true" />
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        use Symfony\Component\DependencyInjection\Definition;
-
-        $container
-            ->setDefinition('request', new Definition())
-            ->setSynthetic(true);
-
-As you see, only the ``synthetic`` option is set. All other options are only used
-to configure how a service is created by the container. As the service isn't
-created by the container, these options are omitted.
-
-Now, you can inject the class by using
-:method:`Container::set <Symfony\\Component\\DependencyInjection\\Container::set>`::
-
-    // ...
-    $container->set('request', new MyRequest(...));
-
 Aliasing
 --------
 
@@ -183,47 +128,6 @@ service by asking for the ``bar`` service like this::
              class: Example\Foo
            bar: "@foo"
 
-
-Requiring Files
----------------
-
-There might be use cases when you need to include another file just before
-the service itself gets loaded. To do so, you can use the ``file`` directive.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        services:
-           foo:
-             class: Example\Foo\Bar
-             file: "%kernel.root_dir%/src/path/to/file/foo.php"
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <services>
-                <service id="foo" class="Example\Foo\Bar">
-                    <file>%kernel.root_dir%/src/path/to/file/foo.php</file>
-                </service>
-            </services>
-        </container>
-
-    .. code-block:: php
-
-        use Symfony\Component\DependencyInjection\Definition;
-
-        $definition = new Definition('Example\Foo\Bar');
-        $definition->setFile('%kernel.root_dir%/src/path/to/file/foo.php');
-        $container->setDefinition('foo', $definition);
-
-Notice that Symfony will internally call the PHP statement ``require_once``,
-which means that your file will be included only once per request.
-
 Decorating Services
 -------------------
 

components/dependency_injection/definitions.rst

@@ -125,3 +125,15 @@ You can also replace any existing method calls with an array of new ones with::
     the container is compiled. Once the container is compiled you cannot
     manipulate service definitions further. To learn more about compiling
     the container see :doc:`/components/dependency_injection/compilation`.
+
+Requiring Files
+~~~~~~~~~~~~~~~
+
+There might be use cases when you need to include another file just before
+the service itself gets loaded. To do so, you can use the
+:method:`Symfony\\Component\\DependencyInjection\\Definition::setFile` method::
+
+    $definition->setFile('/src/path/to/file/foo.php');
+
+Notice that Symfony will internally call the PHP statement ``require_once``,
+which means that your file will be included only once per request.

components/dependency_injection/index.rst

@@ -8,6 +8,7 @@
     types
     parameters
     definitions
+    synthetic_services
     compilation
     tags
     factories

components/dependency_injection/synthetic_services.rst

@@ -0,0 +1,50 @@
+.. index::
+    single: DependencyInjection; Synthetic Services
+
+How to Inject Instances into the Container
+------------------------------------------
+
+When using the container in your application, you sometimes need to inject an
+instance instead of configuring the container to create a new instance.
+
+For instance, if you're using the :doc:`HttpKernel </components/http_kernel/introduction>`
+component with the DependencyInjection component, then the ``kernel``
+service is injected into the container from within the ``Kernel`` class::
+
+    // ...
+    abstract class Kernel implements KernelInterface, TerminableInterface
+    {
+        // ...
+        protected function initializeContainer()
+        {
+            // ...
+            $this->container->set('kernel', $this);
+
+            // ...
+        }
+    }
+
+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).
+
+In order to do so, you have to use
+:method:`Definition::setSynthetic() <Symfony\\Component\\DependencyInjection\\Definition::setSynthetic>`::
+
+    use Symfony\Component\DependencyInjectino\Definition;
+
+    // synthetic services don't specify a class
+    $kernelDefinition = new Definition();
+    $kernelDefinition->setSynthetic(true);
+
+    $container->setDefinition('your_service', $kernelDefinition);
+
+Now, you can inject the instance in the container using
+:method:`Container::set() <Symfony\\Component\\DependencyInjection\\Container::set>`::
+
+    $yourService = new YourObject();
+    $container->set('your_service', $yourService);
+
+``$container->get('your_service')`` will now return the same instance as
+``$yourService``.

components/map.rst.inc

@@ -42,6 +42,7 @@
   * :doc:`/components/dependency_injection/types`
   * :doc:`/components/dependency_injection/parameters`
   * :doc:`/components/dependency_injection/definitions`
+  * :doc:`/components/dependency_injection/synthetic_services`
   * :doc:`/components/dependency_injection/compilation`
   * :doc:`/components/dependency_injection/tags`
   * :doc:`/components/dependency_injection/factories`

cookbook/assetic/asset_management.rst

@@ -183,6 +183,12 @@ To include an image you can use the ``image`` tag.
 You can also use Assetic for image optimization. More information in
 :doc:`/cookbook/assetic/jpeg_optimize`.
 
+.. tip::
+
+    Instead of using Assetic to include images, you may consider using the
+    `LiipImagineBundle`_ community bundle, which allows to compress and
+    manipulate images (rotate, resize, watermark, etc.) before serving them.
+
 .. _cookbook-assetic-cssrewrite:
 
 Fixing CSS Paths with the ``cssrewrite`` Filter
@@ -572,3 +578,5 @@ some isolated directory (e.g. ``/js/compiled``), to keep things organized:
         ) as $url): ?>
             <script src="<?php echo $view->escape($url) ?>"></script>
         <?php endforeach ?>
+
+.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle

cookbook/assetic/jpeg_optimize.rst

@@ -250,4 +250,10 @@ file:
             ),
         ));
 
+.. tip::
+
+    For uploaded images, you can compress and manipulate them using the
+    `LiipImagineBundle`_ community bundle.
+
 .. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html
+.. _`LiipImagineBundle`: http://knpbundles.com/liip/LiipImagineBundle

cookbook/bundles/best_practices.rst

@@ -4,7 +4,7 @@
 Best Practices for Reusable Bundles
 ===================================
 
-There are 2 types of bundles:
+There are two types of bundles:
 
 * Application-specific bundles: only used to build your application;
 * Reusable bundles: meant to be shared across many projects.
@@ -13,12 +13,8 @@ This article is all about how to structure your **reusable bundles** so that
 they're easy to configure and extend. Many of these recommendations do not
 apply to application bundles because you'll want to keep those as simple
 as possible. For application bundles, just follow the practices shown throughout
-the book and cookbook.
-
-.. seealso::
-
-    The best practices for application-specific bundles are discussed in
-    :doc:`/best_practices/introduction`.
+the :doc:`book </book/index>`, the :doc:`cookbook </cookbook/index>` and the
+:doc:`best practices </best_practices/index>` book.
 
 .. index::
    pair: Bundle; Naming conventions
@@ -38,7 +34,7 @@ bundle class name must follow these simple rules:
 
 * Use only alphanumeric characters and underscores;
 * Use a CamelCased name;
-* Use a descriptive and short name (no more than 2 words);
+* Use a descriptive and short name (no more than two words);
 * Prefix the name with the concatenation of the vendor (and optionally the
   category namespaces);
 * Suffix the name with ``Bundle``.
@@ -112,7 +108,7 @@ The following files are mandatory:
     structure to work.
 
 The depth of sub-directories should be kept to the minimal for most used
-classes and files (2 levels at a maximum). More levels can be defined for
+classes and files (two levels at a maximum). More levels can be defined for
 non-strategic, less-used files.
 
 The bundle directory is read-only. If you need to write temporary files, store
@@ -158,7 +154,7 @@ instance, a ``HelloController`` controller is stored in
 ``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
 class name is ``Bundle\HelloBundle\Controller\HelloController``.
 
-All classes and files must follow the Symfony coding :doc:`standards </contributing/code/standards>`.
+All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
 
 Some classes should be seen as facades and should be as short as possible, like
 Commands, Helpers, Listeners, and Controllers.
@@ -181,7 +177,7 @@ Tests
 -----
 
 A bundle should come with a test suite written with PHPUnit and stored under
-the ``Tests/`` directory. Tests should follow the following principles:
+the ``Tests/`` directory. Tests should follow these principles:
 
 * The test suite must be executable with a simple ``phpunit`` command run from
   a sample application;
@@ -190,13 +186,14 @@ the ``Tests/`` directory. Tests should follow the following principles:
 * The tests should cover at least 95% of the code base.
 
 .. note::
+
    A test suite must not contain ``AllTests.php`` scripts, but must rely on the
    existence of a ``phpunit.xml.dist`` file.
 
 Documentation
 -------------
 
-All classes and functions must come with full PHPDoc.
+All classes and functions must be fully documented using `PHPDoc`_ tags.
 
 Extensive documentation should also be provided in the
 :doc:`reStructuredText </contributing/documentation/format>` format, under
@@ -233,8 +230,8 @@ following standardized instructions in your ``README.md`` file.
         Step 2: Enable the Bundle
         -------------------------
 
-        Then, enable the bundle by adding the following line in the `app/AppKernel.php`
-        file of your project:
+        Then, enable the bundle by adding it to the list of registered bundles
+        in the `app/AppKernel.php` file of your project:
 
         ```php
         <?php
@@ -279,8 +276,8 @@ following standardized instructions in your ``README.md`` file.
         Step 2: Enable the Bundle
         -------------------------
 
-        Then, enable the bundle by adding the following line in the ``app/AppKernel.php``
-        file of your project:
+        Then, enable the bundle by adding it to the list of registered bundles
+        in the ``app/AppKernel.php`` file of your project:
 
         .. code-block:: php
 
@@ -306,8 +303,11 @@ following standardized instructions in your ``README.md`` file.
 
         .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
 
-This template assumes that your bundle is in its ``1.x`` version. If not, change
-the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)
+The example above assumes that you are installing the latest stable version of
+the bundle, where you don't have to provide the package version number
+(e.g. ``composer require friendsofsymfony/user-bundle``). If the installation
+instructions refer to some past bundle version or to some unstable version,
+include the version constraint (e.g. ``composer require friendsofsymfony/user-bundle "~2.0@dev"``).
 
 Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
 explain other required installation tasks, such as registering routes or
@@ -330,7 +330,8 @@ Translation Files
 -----------------
 
 If a bundle provides message translations, they must be defined in the XLIFF
-format; the domain should be named after the bundle name (``bundle.hello``).
+format; the :ref:`translation domain <using-message-domains>` should be named
+after the bundle name (``bundle.hello``).
 
 A bundle must not override existing messages from another bundle.
 
@@ -369,18 +370,12 @@ The end user can provide values in any configuration file:
         // app/config/config.php
         $container->setParameter('acme_hello.email.from', 'fabien@example.com');
 
-    .. code-block:: ini
-
-        ; app/config/config.ini
-        [parameters]
-        acme_hello.email.from = fabien@example.com
-
 Retrieve the configuration parameters in your code from the container::
 
     $container->getParameter('acme_hello.email.from');
 
 Even if this mechanism is simple enough, you are highly encouraged to use the
-semantic configuration described in the cookbook.
+:doc:`semantic bundle configuration </cookbook/bundles/extension>` instead.
 
 .. note::
 
@@ -435,3 +430,4 @@ Learn more from the Cookbook
 * :doc:`/cookbook/bundles/extension`
 
 .. _standards: http://www.php-fig.org/psr/psr-4/
+.. _`PHPDoc`: https://en.wikipedia.org/wiki/PHPDoc