Merge branch '2.4' into 2.5

* 2.4: (38 commits) use relative path to page fix xml to specify a method replaced old way of specifying http method by the new one Fixing a mistake Fix use mistakes. [#3944] Tiny addition to mention multiple connections Update dbal.rst [#3888] Changing base template title back [Components] consistent & complete config examples Check for api_key in request Update api_key_authentication.rst - POST Method Fixed typos Added link to JSFiddle example some minor improvements describe the usage of the RegisterListenersPass Update deployment-tools.rst Rewrote Extension & Configuration docs add order of translation formats Fix class name in ConsoleTerminateListener example Fixed the code snippets for the expression language functions ...
symfony · Aug 16, 2014 · bb39863 · bb39863
2 parents 5ab5246 + 303ff29
commit bb39863
Show file tree

Hide file tree

Showing 55 changed files with 1,972 additions and 1,243 deletions.
diff --git a/book/controller.rst b/book/controller.rst
@@ -170,10 +170,16 @@ to the controller:
     .. code-block:: php
 
         // app/config/routing.php
+        use Symfony\Component\Routing\Route;
+        use Symfony\Component\Routing\RouteCollection;
+
+        $collection = new RouteCollection();
         $collection->add('hello', new Route('/hello/{name}', array(
             '_controller' => 'AcmeHelloBundle:Hello:index',
         )));
 
+        return $collection;
+
 Going to ``/hello/ryan`` now executes the ``HelloController::indexAction()``
 controller and passes in ``ryan`` for the ``$name`` variable. Creating a
 "page" means simply creating a controller method and associated route.
@@ -257,11 +263,17 @@ example:
     .. code-block:: php
 
         // app/config/routing.php
+        use Symfony\Component\Routing\Route;
+        use Symfony\Component\Routing\RouteCollection;
+
+        $collection = new RouteCollection();
         $collection->add('hello', new Route('/hello/{firstName}/{lastName}', array(
             '_controller' => 'AcmeHelloBundle:Hello:index',
             'color'       => 'green',
         )));
 
+        return $collection;
+
 The controller for this can take several arguments::
 
     public function indexAction($firstName, $lastName, $color)

diff --git a/book/doctrine.rst b/book/doctrine.rst
@@ -85,18 +85,16 @@ information. By convention, this information is usually configured in an
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
                 <doctrine:config>
                     <doctrine:dbal
                         driver="%database_driver%"
                         host="%database_host%"
                         dbname="%database_name%"
                         user="%database_user%"
-                        password="%database_password%"
-                    />
+                        password="%database_password%" />
                 </doctrine:config>
-
             </container>
 
         .. code-block:: php
@@ -175,16 +173,14 @@ for you:
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
                 xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
-
-                <doctrine:config
-                    driver="pdo_sqlite"
-                    path="%kernel.root_dir%/sqlite.db"
-                    charset="UTF-8"
-                >
-                    <!-- ... -->
-                </doctrine:config>
+                    http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
+                <doctrine:config>
+                    <doctrine:dbal
+                        driver="pdo_sqlite"
+                        path="%kernel.root_dir%/sqlite.db"
+                        charset="UTF-8" />
+                </doctrine:config>
             </container>
 
         .. code-block:: php
@@ -319,17 +315,17 @@ in a number of different formats including YAML, XML or directly inside the
         <!-- src/Acme/StoreBundle/Resources/config/doctrine/Product.orm.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Acme\StoreBundle\Entity\Product" table="product">
-                <id name="id" type="integer" column="id">
+                <id name="id" type="integer">
                     <generator strategy="AUTO" />
                 </id>
-                <field name="name" column="name" type="string" length="100" />
-                <field name="price" column="price" type="decimal" scale="2" />
-                <field name="description" column="description" type="text" />
+                <field name="name" type="string" length="100" />
+                <field name="price" type="decimal" scale="2" />
+                <field name="description" type="text" />
             </entity>
         </doctrine-mapping>
 
@@ -826,13 +822,15 @@ To do this, add the name of the repository class to your mapping definition:
         <!-- src/Acme/StoreBundle/Resources/config/doctrine/Product.orm.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+            <entity
+                name="Acme\StoreBundle\Entity\Product"
+                repository-class="Acme\StoreBundle\Entity\ProductRepository">
 
-            <entity name="Acme\StoreBundle\Entity\Product"
-                    repository-class="Acme\StoreBundle\Entity\ProductRepository">
-                    <!-- ... -->
+                <!-- ... -->
             </entity>
         </doctrine-mapping>
 
@@ -945,17 +943,18 @@ To relate the ``Category`` and ``Product`` entities, start by creating a
     .. code-block:: xml
 
         <!-- src/Acme/StoreBundle/Resources/config/doctrine/Category.orm.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Acme\StoreBundle\Entity\Category">
                 <!-- ... -->
-                <one-to-many field="products"
+                <one-to-many
+                    field="products"
                     target-entity="Product"
-                    mapped-by="category"
-                />
+                    mapped-by="category" />
 
                 <!--
                     don't forget to init the collection in
@@ -1023,22 +1022,21 @@ object, you'll want to add a ``$category`` property to the ``Product`` class:
     .. code-block:: xml
 
         <!-- src/Acme/StoreBundle/Resources/config/doctrine/Product.orm.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Acme\StoreBundle\Entity\Product">
                 <!-- ... -->
-                <many-to-one field="category"
+                <many-to-one
+                    field="category"
                     target-entity="Category"
                     inversed-by="products"
-                    join-column="category"
-                >
-                    <join-column
-                        name="category_id"
-                        referenced-column-name="id"
-                    />
+                    join-column="category">
+
+                    <join-column name="category_id" referenced-column-name="id" />
                 </many-to-one>
             </entity>
         </doctrine-mapping>
@@ -1306,6 +1304,8 @@ the current date, only when the entity is first persisted (i.e. inserted):
 
     .. code-block:: php-annotations
 
+        // src/Acme/StoreBundle/Entity/Product.php
+
         /**
          * @ORM\PrePersist
          */
@@ -1328,16 +1328,15 @@ the current date, only when the entity is first persisted (i.e. inserted):
         <!-- src/Acme/StoreBundle/Resources/config/doctrine/Product.orm.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Acme\StoreBundle\Entity\Product">
-                    <!-- ... -->
-                    <lifecycle-callbacks>
-                        <lifecycle-callback type="prePersist"
-                            method="setCreatedAtValue" />
-                    </lifecycle-callbacks>
+                <!-- ... -->
+                <lifecycle-callbacks>
+                    <lifecycle-callback type="prePersist" method="setCreatedAtValue" />
+                </lifecycle-callbacks>
             </entity>
         </doctrine-mapping>
 

diff --git a/book/forms.rst b/book/forms.rst
@@ -129,7 +129,7 @@ corresponding to the ``task`` and ``dueDate`` properties of the ``Task`` class.
 You've also assigned each a "type" (e.g. ``text``, ``date``), which, among
 other things, determines which HTML form tag(s) is rendered for that field.
 
-Finally, you added a submit button with a custom label for submitting the form to 
+Finally, you added a submit button with a custom label for submitting the form to
 the server.
 
 .. versionadded:: 2.3
@@ -1126,20 +1126,21 @@ easy to use in your application.
         <?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>
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
             <services>
-               <service id="acme_demo.form.type.task"
-                class="Acme\TaskBundle\Form\Type\TaskType">
-                  <tag name="form.type" alias="task" />
-               </service>
+                <service
+                    id="acme_demo.form.type.task"
+                    class="Acme\TaskBundle\Form\Type\TaskType">
+
+                    <tag name="form.type" alias="task" />
+                </service>
             </services>
         </container>
 
     .. code-block:: php
 
         // src/Acme/TaskBundle/Resources/config/services.php
-        use Symfony\Component\DependencyInjection\Definition;
-
         $container
             ->register(
                 'acme_demo.form.type.task',
@@ -1590,13 +1591,13 @@ file:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:twig="http://symfony.com/schema/dic/twig"
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+                http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
-                    <twig:form>
-                        <twig:resource>AcmeTaskBundle:Form:fields.html.twig</twig:resource>
-                    </twig:form>
-                    <!-- ... -->
+                <twig:form>
+                    <twig:resource>AcmeTaskBundle:Form:fields.html.twig</twig:resource>
+                </twig:form>
+                <!-- ... -->
             </twig:config>
         </container>
 
@@ -1676,7 +1677,7 @@ file:
             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">
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <framework:templating>

diff --git a/book/http_cache.rst b/book/http_cache.rst
@@ -763,6 +763,12 @@ both worlds. In other words, by using both expiration and validation, you
 can instruct the cache to serve the cached content, while checking back
 at some interval (the expiration) to verify that the content is still valid.
 
+.. tip::
+
+    You can also define HTTP caching headers for expiration and validation by using
+    annotations. See the 
+    :doc:`FrameworkExtraBundle documentation </bundles/SensioFrameworkExtraBundle/annotations/cache>`.
+
 .. index::
     pair: Cache; Configuration
 
@@ -866,8 +872,7 @@ First, to use ESI, be sure to enable it in your application configuration:
             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">
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
                 <!-- ... -->
@@ -880,7 +885,7 @@ First, to use ESI, be sure to enable it in your application configuration:
         // app/config/config.php
         $container->loadFromExtension('framework', array(
             // ...
-            'esi'    => array('enabled' => true),
+            'esi' => array('enabled' => true),
         ));
 
 Now, suppose you have a page that is relatively static, except for a news
@@ -988,8 +993,9 @@ that must be enabled in your configuration:
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/framework"
             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">
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
+            <!-- ... -->
             <framework:config>
                 <framework:fragments path="/_fragment" />
             </framework:config>

diff --git a/book/http_fundamentals.rst b/book/http_fundamentals.rst
@@ -433,6 +433,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
 
     .. code-block:: xml
 
+        <!-- app/config/config.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -447,8 +448,8 @@ by adding an entry for ``/contact`` to your routing configuration file:
     .. code-block:: php
 
         // app/config/routing.php
-        use Symfony\Component\Routing\RouteCollection;
         use Symfony\Component\Routing\Route;
+        use Symfony\Component\Routing\RouteCollection;
 
         $collection = new RouteCollection();
         $collection->add('contact', new Route('/contact', array(

diff --git a/book/internals.rst b/book/internals.rst
@@ -601,7 +601,7 @@ the configuration for the development environment:
             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/webprofiler http://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd
-                                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <!-- load the profiler -->
             <framework:config>
@@ -611,9 +611,7 @@ the configuration for the development environment:
             <!-- enable the web profiler -->
             <webprofiler:config
                 toolbar="true"
-                intercept-redirects="true"
-                verbose="true"
-            />
+                intercept-redirects="true" />
         </container>
 
     .. code-block:: php
@@ -627,7 +625,6 @@ the configuration for the development environment:
         $container->loadFromExtension('web_profiler', array(
             'toolbar'             => true,
             'intercept_redirects' => true,
-            'verbose'             => true,
         ));
 
 When ``only_exceptions`` is set to ``true``, the profiler only collects data
@@ -657,18 +654,18 @@ If you enable the web profiler, you also need to mount the profiler routes:
 
             <import
                 resource="@WebProfilerBundle/Resources/config/routing/profiler.xml"
-                prefix="/_profiler"
-            />
+                prefix="/_profiler" />
         </routes>
 
     .. code-block:: php
 
-        $collection->addCollection(
-            $loader->import(
-                "@WebProfilerBundle/Resources/config/routing/profiler.xml"
-            ),
-            '/_profiler'
-        );
+        use Symfony\Component\Routing\RouteCollection;
+
+        $profiler = $loader->import('@WebProfilerBundle/Resources/config/routing/profiler.xml');
+        $profiler->addPrefix('/_profiler');
+
+        $collection = new RouteCollection();
+        $collection->addCollection($profiler);
 
 As the profiler adds some overhead, you might want to enable it only under
 certain circumstances in the production environment. The ``only_exceptions``