Merge branch '2.7' into 2.8

* 2.7:
  Correcting reference to `isSuccessful` method for Process
  Update custom_constraint.rst
  Minor fix
  Fixed typo
  Discourage the use of controllers as services
  Add constants to BC promise
  Remove complex DI extension information and link the cookbook article instead
  Trying to remove some duplication and some extra details

Author: xabbuh

book/controller.rst

@@ -399,14 +399,6 @@ that's available to you with or without the use of the base
 action is to look in the
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
 
-.. seealso::
-
-    If you're curious about how a controller would work that did *not*
-    extend this base ``Controller`` class, check out cookbook article
-    :doc:`Controllers as Services </cookbook/controller/service>`.
-    This is optional, but can give you more control over the exact
-    objects/dependencies that are injected into your controller.
-
 .. index::
    single: Controller; Redirecting
 

book/service_container.rst

@@ -152,9 +152,7 @@ later how you can configure a service that has multiple instances in the
     In this example, the controller extends Symfony's base Controller, which
     gives you access to the service container itself. You can then use the
     ``get`` method to locate and retrieve the ``app.mailer`` service from
-    the service container. You can also define your :doc:`controllers as services </cookbook/controller/service>`.
-    This is a bit more advanced and not necessary, but it allows you to inject
-    only the services you need into your controller.
+    the service container.
 
 .. _book-service-container-parameters:
 
@@ -277,10 +275,10 @@ be imported from inside this file in one way or another. This gives you absolute
 flexibility over the services in your application.
 
 External service configuration can be imported in two different ways. The first
-method, commonly used to import container configuration from the bundles you've
-created - is via the ``imports`` directive. The second method, although slightly more
-complex offers more flexibility and is commonly used to import third-party bundle
-configuration. Read on to learn more about both methods.
+method, commonly used to import other resources, is via the ``imports``
+directive. The second method, using dependency injection extensions, is used by
+third-party bundles to load the configuration. Read on to learn more about both
+methods.
 
 .. index::
    single: Service Container; Imports
@@ -291,20 +289,16 @@ Importing Configuration with ``imports``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 So far, you've placed your ``app.mailer`` service container definition directly
-in the application configuration file (e.g. ``app/config/config.yml``). Of
-course, since the ``Mailer`` class itself lives inside the AppBundle, it
-makes more sense to put the ``app.mailer`` container definition inside the
-bundle as well.
-
-First, move the ``app.mailer`` container definition into a new container resource
-file inside AppBundle. If the ``Resources`` or ``Resources/config``
-directories don't exist, create them.
+in the services configuration file (e.g. ``app/config/services.yml``). If your
+application ends up having many services, this file becomes huge and hard to
+maintain. To avoid this, you can split your service configuration into multiple
+service files:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # src/AppBundle/Resources/config/services.yml
+        # app/config/services/mailer.yml
         parameters:
             app.mailer.transport: sendmail
 
@@ -315,7 +309,7 @@ directories don't exist, create them.
 
     .. code-block:: xml
 
-        <!-- src/AppBundle/Resources/config/services.xml -->
+        <!-- app/config/services/mailer.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"
@@ -335,7 +329,7 @@ directories don't exist, create them.
 
     .. code-block:: php
 
-        // src/AppBundle/Resources/config/services.php
+        // app/config/services/mailer.php
         use Symfony\Component\DependencyInjection\Definition;
 
         $container->setParameter('app.mailer.transport', 'sendmail');
@@ -345,46 +339,42 @@ directories don't exist, create them.
             array('%app.mailer.transport%')
         ));
 
-The definition itself hasn't changed, only its location. Of course the service
-container doesn't know about the new resource file. Fortunately, you can
-easily import the resource file using the ``imports`` key in the application
-configuration.
+The definition itself hasn't changed, only its location. To make the service
+container load the definitions in this resource file, use the ``imports`` key
+in any already loaded resource (e.g. ``app/config/services.yml`` or
+``app/config/config.yml``):
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # app/config/config.yml
+        # app/config/services.yml
         imports:
-            - { resource: '@AppBundle/Resources/config/services.yml' }
+            - { resource: services/mailer.yml }
 
     .. code-block:: xml
 
-        <!-- app/config/config.xml -->
+        <!-- app/config/services.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">
 
             <imports>
-                <import resource="@AppBundle/Resources/config/services.xml"/>
+                <import resource="services/mailer.xml"/>
             </imports>
         </container>
 
     .. code-block:: php
 
-        // app/config/config.php
-        $loader->import('@AppBundle/Resources/config/services.php');
+        // app/config/services.php
+        $loader->import('services/mailer.php');
 
-.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc
+The ``resource`` location, for files, is either a relative path from the
+current file or an absolute path.
 
-The ``imports`` directive allows your application to include service container
-configuration resources from any other location (most commonly from bundles).
-The ``resource`` location, for files, is the absolute path to the resource
-file. The special ``@AppBundle`` syntax resolves the directory path
-of the AppBundle bundle. This helps you specify the path to the resource
-without worrying later if you move the AppBundle to a different directory.
+.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc
 
 .. index::
    single: Service Container; Extension configuration
@@ -394,31 +384,14 @@ without worrying later if you move the AppBundle to a different directory.
 Importing Configuration via Container Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When developing in Symfony, you'll most commonly use the ``imports`` directive
-to import container configuration from the bundles you've created specifically
-for your application. Third-party bundle container configuration, including
-Symfony core services, are usually loaded using another method that's more
-flexible and easy to configure in your application.
-
-Here's how it works. Internally, each bundle defines its services very much
-like you've seen so far. Namely, a bundle uses one or more configuration
-resource files (usually XML) to specify the parameters and services for that
-bundle. However, instead of importing each of these resources directly from
-your application configuration using the ``imports`` directive, you can simply
-invoke a *service container extension* inside the bundle that does the work for
-you. A service container extension is a PHP class created by the bundle author
-to accomplish two things:
-
-* import all service container resources needed to configure the services for
-  the bundle;
+Third-party bundle container configuration, including Symfony core services,
+are usually loaded using another method that's more flexible and easy to
+configure in your application.
 
-* provide semantic, straightforward configuration so that the bundle can
-  be configured without interacting with the flat parameters of the bundle's
-  service container configuration.
-
-In other words, a service container extension configures the services for
-a bundle on your behalf. And as you'll see in a moment, the extension provides
-a sensible, high-level interface for configuring the bundle.
+Internally, each bundle defines its services like you've seen so far. However,
+these files aren't imported using the ``import`` directive. These bundles use a
+*dependency injection extension* to load the files. The extension also allows
+bundles to provide configuration to dynamically load some services.
 
 Take the FrameworkBundle - the core Symfony Framework bundle - as an
 example. The presence of the following code in your application configuration
@@ -430,10 +403,8 @@ invokes the service container extension inside the FrameworkBundle:
 
         # app/config/config.yml
         framework:
-            secret:          xxxxxxxxxx
-            form:            true
-            csrf_protection: true
-            router:        { resource: '%kernel.root_dir%/config/routing.yml' }
+            secret: xxxxxxxxxx
+            form:   true
             # ...
 
     .. code-block:: xml
@@ -443,15 +414,13 @@ invokes the service container extension inside the FrameworkBundle:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
 
             <framework:config secret="xxxxxxxxxx">
                 <framework:form />
-                <framework:csrf-protection />
-                <framework:router resource="%kernel.root_dir%/config/routing.xml" />
+
                 <!-- ... -->
             </framework>
         </container>
@@ -460,51 +429,31 @@ invokes the service container extension inside the FrameworkBundle:
 
         // app/config/config.php
         $container->loadFromExtension('framework', array(
-            'secret'          => 'xxxxxxxxxx',
-            'form'            => array(),
-            'csrf-protection' => array(),
-            'router'          => array(
-                'resource' => '%kernel.root_dir%/config/routing.php',
-            ),
+            'secret' => 'xxxxxxxxxx',
+            'form'   => array(),
 
             // ...
         ));
 
-When the configuration is parsed, the container looks for an extension that
-can handle the ``framework`` configuration directive. The extension in question,
-which lives in the FrameworkBundle, is invoked and the service configuration
-for the FrameworkBundle is loaded. If you remove the ``framework`` key
-from your application configuration file entirely, the core Symfony services
-won't be loaded. The point is that you're in control: the Symfony Framework
-doesn't contain any magic or perform any actions that you don't have control
-over.
-
-Of course you can do much more than simply "activate" the service container
-extension of the FrameworkBundle. Each extension allows you to easily
-customize the bundle, without worrying about how the internal services are
-defined.
-
-In this case, the extension allows you to customize the ``error_handler``,
-``csrf_protection``, ``router`` configuration and much more. Internally,
-the FrameworkBundle uses the options specified here to define and configure
-the services specific to it. The bundle takes care of creating all the necessary
-``parameters`` and ``services`` for the service container, while still allowing
-much of the configuration to be easily customized. As a bonus, most
-service container extensions are also smart enough to perform validation -
-notifying you of options that are missing or the wrong data type.
+When the resources are parsed, the container looks for an extension that
+can handle the ``framework`` directive. The extension in question, which lives
+in the FrameworkBundle, is invoked and the service configuration for the
+FrameworkBundle is loaded.
+
+The settings under the ``framework`` directive (e.g. ``form: true``) indicate
+that the extension should load all services related to the Form component. If
+form was disabled, these services wouldn't be loaded and Form integration would
+not be available.
 
 When installing or configuring a bundle, see the bundle's documentation for
 how the services for the bundle should be installed and configured. The options
 available for the core bundles can be found inside the :doc:`Reference Guide </reference/index>`.
 
-.. note::
-
-   Natively, the service container only recognizes the ``parameters``,
-   ``services``, and ``imports`` directives. Any other directives
-   are handled by a service container extension.
+.. seealso::
 
-If you want to expose user friendly configuration in your own bundles, read the
-":doc:`/cookbook/bundles/extension`" cookbook recipe.
+    If you want to use dependency injection extensions in your own shared
+    bundles and provide user friendly configuration, take a look at the
+    ":doc:`/cookbook/bundles/extension`" cookbook recipe.
 
 .. index::
    single: Service Container; Referencing services

components/console/helpers/debug_formatter.rst

@@ -122,7 +122,7 @@ notify this to the users::
         $debugFormatter->stop(
             spl_object_hash($process),
             'Some command description',
-            $process->isSuccessfull()
+            $process->isSuccessful()
         )
     );
 

components/http_kernel/introduction.rst

@@ -264,9 +264,6 @@ will be called after another event - ``kernel.controller`` - is dispatched.
        is passed to it. This step is also specific to the  :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerResolver`
        sub-class used by the Symfony Framework.
 
-       There are also a few other variations on the above process (e.g. if
-       you're registering your controllers as services).
-
 .. _component-http-kernel-kernel-controller:
 
 3) The ``kernel.controller`` Event

contributing/code/bc.rst

@@ -165,6 +165,10 @@ Add type hint to an argument                    No
 Remove type hint of an argument                 No
 Change argument type                            No
 Change return type                              No
+**Constants**
+Add constant                                    Yes
+Remove constant                                 No
+Change value of a constant                      Yes [1]_ [5]_
 ==============================================  ==============
 
 Changing Classes
@@ -248,6 +252,10 @@ Change return type                                  Yes
 **Static Methods**
 Turn non static into static                         No
 Turn static into non static                         No
+**Constants**
+Add constant                                        Yes
+Remove constant                                     No
+Change value of a constant                          Yes [1]_ [5]_
 ==================================================  ==============
 
 .. [1] Should be avoided. When done, this change must be documented in the
@@ -262,6 +270,13 @@ Turn static into non static                         No
 .. [4] When changing the parent class, the original parent class must remain an
        ancestor of the class.
 
+.. [5] The value of a constant may only be changed when the constants aren't
+       used in configuration (e.g. Yaml and XML files), as these do not support
+       constants and have to hardcode the value. For instance, event name
+       constants can't change the value without introducing a BC break.
+       Additionally, if a constant will likely be used in objects that are
+       serialized, the value of a constant should not be changed.
+
 .. _Semantic Versioning: http://semver.org/
 .. _scalar type: http://php.net/manual/en/function.is-scalar.php
 .. _boolean values: http://php.net/manual/en/function.boolval.php