Merge branch '2.8'

* 2.8: (24 commits)
  [symfony#5331] Tiny typo
  [symfony#5373] Small tweak per Stof's comment
  Added depreciation note for the cascade_validation constraint and updated position of depreciation notes
  [PSR-7] Bridge documentation
  Fix after install URL and new photo since AcmeDemoBundle is not part of 2.7
  Fixed a minor grammar issue
  Fixed typos
  Link to the official repository of the bundle.
  Added mentions to some popular (and useful) Symfony bundles
  [symfony#5095] Fixing a typo and updating to a more realistic example
  [Components][ClassLoader] remove DebugClassLoader
  [symfony#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
  Updated the list of reserved domains and the URL reference
  Use the reserved domains example.com and example.org
  ...

Author: weaverryan

Diff for: book/installation.rst

@@ -169,7 +169,8 @@ browsing the project directory and executing this command:
     $ cd my_project_name/
     $ php app/console server:run
 
-Then, open your browser and access the ``http://localhost:8000`` URL to see the
+Then, open your browser and access the ``http://localhost:8000/app/example``
+URL to see the
 Welcome page of Symfony:
 
 .. image:: /images/quick_tour/welcome.png

Diff for: 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>
@@ -1381,3 +1386,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

Diff for: components/class_loader/class_loader.rst

@@ -12,8 +12,7 @@ load all of your project's classes.
 
     You can use both the ``ApcClassLoader`` and the ``XcacheClassLoader`` to
     :doc:`cache </components/class_loader/cache_class_loader>` a ``ClassLoader``
-    instance or the ``DebugClassLoader`` to :doc:`debug </components/class_loader/debug_class_loader>`
-    it.
+    instance.
 
 Usage
 -----

Diff for: components/class_loader/debug_class_loader.rst

@@ -1,6 +1,3 @@
-.. index::
-    single: ClassLoader; DebugClassLoader
-
 Debugging a Class Loader
 ========================
 

Diff for: components/class_loader/index.rst

@@ -9,5 +9,9 @@ ClassLoader
     psr4_class_loader
     map_class_loader
     cache_class_loader
-    debug_class_loader
     class_map_generator
+
+.. toctree::
+    :hidden:
+
+    debug_class_loader

Diff for: components/class_loader/introduction.rst

@@ -23,12 +23,14 @@ the class. Symfony provides three autoloaders, which are able to load your class
 * :doc:`/components/class_loader/map_class_loader`: loads classes using
   a static map from class name to file path.
 
-Additionally, the Symfony ClassLoader component ships with a set of wrapper
-classes which can be used to add additional functionality on top of existing
-autoloaders:
-
-* :doc:`/components/class_loader/cache_class_loader`
-* :doc:`/components/class_loader/debug_class_loader`
+Additionally, the Symfony ClassLoader component ships with a wrapper class
+which makes it possible
+:doc:`to cache the results of a class loader </components/class_loader/cache_class_loader>`.
+
+When using the :doc:`Debug component </components/debug/introduction>`, you
+can also use a special :doc:`DebugClassLoader </components/debug/class_loader>`
+that eases debugging by throwing more helpful exceptions when a class could
+not be found by a class loader.
 
 Installation
 ------------

Diff for: 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
 -------------------
 

Diff for: 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.

Diff for: components/dependency_injection/index.rst

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

Diff for: 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``.

Diff for: components/map.rst.inc

@@ -11,7 +11,6 @@
   * :doc:`/components/class_loader/psr4_class_loader`
   * :doc:`/components/class_loader/map_class_loader`
   * :doc:`/components/class_loader/cache_class_loader`
-  * :doc:`/components/class_loader/debug_class_loader`
   * :doc:`/components/class_loader/class_map_generator`
 
 * :doc:`/components/config/index`
@@ -47,6 +46,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`

Diff for: contributing/documentation/standards.rst

@@ -57,6 +57,9 @@ Code Examples
   Unless the example requires a custom bundle, make sure to always use the
   ``AppBundle`` bundle to store your code;
 * Use ``Acme`` when the code requires a vendor name;
+* Use ``example.com`` as the domain of sample URLs and ``example.org`` and
+  ``example.net`` when additional domains are required. All of these domains are
+  `reserved by the IANA`_.
 * To avoid horizontal scrolling on code blocks, we prefer to break a line
   correctly if it crosses the 85th character;
 * When you fold one or more lines of code, place ``...`` in a comment at the point
@@ -174,6 +177,7 @@ In addition, documentation follows these rules:
 
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
+.. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
 .. _`American English`: http://en.wikipedia.org/wiki/American_English
 .. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/
 .. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles

Diff for: 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

Diff for: 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