Merge branch '2.4'

Author: weaverryan

README.markdown

@@ -7,9 +7,9 @@ Contributing
 ------------
 
 >**Note**
->Unless you're documenting a feature that's new to a specific version of Symfony
->(e.g. Symfony 2.3), all pull requests must be based off of the **2.2** branch,
->**not** the master or 2.3 branch.
+>Unless you're documenting a feature that was introduced *after* Symfony 2.3 
+>(e.g. in Symfony 2.4), all pull requests must be based off of the **2.3** branch,
+>**not** the master or older branches.
 
 We love contributors! For more information on how you can contribute to the
 Symfony documentation, please read

book/controller.rst

@@ -513,7 +513,10 @@ value to each variable.
         $subRequest = $request->duplicate(array(), null, $path);
 
         $httpKernel = $this->container->get('http_kernel');
-        $response = $httpKernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
+        $response = $httpKernel->handle(
+            $subRequest,
+            HttpKernelInterface::SUB_REQUEST
+        );
 
 .. index::
    single: Controller; Rendering templates
@@ -579,7 +582,8 @@ The Symfony templating engine is explained in great detail in the
             'AcmeHelloBundle:Hello/Greetings:index.html.twig',
             array('name' => $name)
         );
-        // index.html.twig found in Resources/views/Hello/Greetings is rendered.
+        // index.html.twig found in Resources/views/Hello/Greetings
+        // is rendered.
 
 .. index::
    single: Controller; Accessing services

book/doctrine.rst

@@ -623,7 +623,9 @@ You can also take advantage of the useful ``findBy`` and ``findOneBy`` methods
 to easily fetch objects based on multiple conditions::
 
     // query for one product matching be name and price
-    $product = $repository->findOneBy(array('name' => 'foo', 'price' => 19.99));
+    $product = $repository->findOneBy(
+        array('name' => 'foo', 'price' => 19.99)
+    );
 
     // query for all products matching the name, ordered by price
     $products = $repository->findBy(
@@ -1144,7 +1146,8 @@ Now you can see this new code in action! Imagine you're inside a controller::
             $em->flush();
 
             return new Response(
-                'Created product id: '.$product->getId().' and category id: '.$category->getId()
+                'Created product id: '.$product->getId()
+                .' and category id: '.$category->getId()
             );
         }
     }
@@ -1253,8 +1256,8 @@ following method to the ``ProductRepository`` class::
     public function findOneByIdJoinedToCategory($id)
     {
         $query = $this->getEntityManager()
-            ->createQuery('
-                SELECT p, c FROM AcmeStoreBundle:Product p
+            ->createQuery(
+                'SELECT p, c FROM AcmeStoreBundle:Product p
                 JOIN p.category c
                 WHERE p.id = :id'
             )->setParameter('id', $id);
@@ -1478,8 +1481,8 @@ and ``nullable``. Take a few examples:
         protected $name;
 
         /**
-         * A string field of length 150 that persists to an "email_address" column
-         * and has a unique index.
+         * A string field of length 150 that persists to an
+         * "email_address" column and has a unique index.
          *
          * @ORM\Column(name="email_address", unique=true, length=150)
          */
@@ -1489,13 +1492,14 @@ and ``nullable``. Take a few examples:
 
         fields:
             # A string field length 255 that cannot be null
-            # (reflecting the default values for the "length" and *nullable* options)
-            # type attribute is necessary in YAML definitions
+            # (reflecting the default values for the "length"
+            # and *nullable* options) type attribute is
+            # necessary in YAML definitions
             name:
                 type: string
 
-            # A string field of length 150 that persists to an "email_address" column
-            # and has a unique index.
+            # A string field of length 150 that persists to
+            # an "email_address" column and has a unique index.
             email:
                 type: string
                 column: email_address
@@ -1506,8 +1510,9 @@ and ``nullable``. Take a few examples:
 
         <!--
             A string field length 255 that cannot be null
-            (reflecting the default values for the "length" and *nullable* options)
-            type attribute is necessary in XML definitions
+            (reflecting the default values for the "length"
+            and *nullable* options) type attribute is
+            necessary in XML definitions
         -->
         <field name="name" type="string" />
         <field name="email"

book/forms.rst

@@ -645,7 +645,8 @@ the documentation for each type.
         ))
 
     The label for a field can also be set in the template rendering the
-    form, see below.
+    form, see below. If you don't need a label associated to your input,
+    you can disable it by setting its value to ``false``.
 
 .. index::
    single: Forms; Field type guessing

changelog.rst

@@ -0,0 +1,66 @@
+.. index::
+    single: CHANGELOG
+
+The Documentation Changelog
+===========================
+
+This documentation is always changing: All new features need new documentation
+and bugs/typos get fixed. This article holds all important changes of the
+documentation.
+
+.. tip::
+
+    Do you also want to participate in the Symfony Documentation? Take a look
+    at the ":doc:`/contributing/documentation`" article.
+
+January, 2014
+-------------
+
+New Documentation
+~~~~~~~~~~~~~~~~~
+
+No changes
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+- `e385d28 <https://github.com/symfony/symfony-docs/commit/e385d28bee7c7418c8175d43befc4954a43a300c>`_ #3503 file extension correction xfliff to xliff (nixilla)
+- `7fe0de3 <https://github.com/symfony/symfony-docs/commit/7fe0de330b2d72155b6b7ec87c59f5a7e7ee4881>`_ #3475 Fixed doc for framework.session.cookie_lifetime refrence. (tyomo4ka)
+- `8155e4c <https://github.com/symfony/symfony-docs/commit/8155e4cab70e481962a4775274a4412a4465ecdc>`_ #3473 Update proxy_examples.rst (AZielinski)
+- `c205bc6 <https://github.com/symfony/symfony-docs/commit/c205bc6798bac34741f2d4d91450aac75ab14b93>`_ #3468 enclose YAML string with double quotes to fix syntax highlighting (xabbuh)
+- `89963cc <https://github.com/symfony/symfony-docs/commit/89963cc246263e7e7cdecd3cad1f019ff9cb28a5>`_ #3463 Fix typos in cookbook/testing/database (ifdattic)
+- `e0a52ec <https://github.com/symfony/symfony-docs/commit/e0a52ecf0cbcf1b5aa029f323588880080f5c6f3>`_ #3460 remove confusing outdated note on interactive rebasing (xabbuh)
+- `6831b13 <https://github.com/symfony/symfony-docs/commit/6831b1337f99c26d9f04eb82990cc3b3ac128de0>`_ #3455 [Contributing][Code] fix indentation so that the text is rendered properly (xabbuh)
+- `ea5816f <https://github.com/symfony/symfony-docs/commit/ea5816f571309decd946bf30aa0b3b84fffacb9e>`_ #3433 [WIP][Reference][Form Types] Update "radio" form type (bicpi)
+- `42c80d1 <https://github.com/symfony/symfony-docs/commit/42c80d12ac760f40834afef76fd42db83d4d4a33>`_ #3448 Overridden tweak (weaverryan)
+- `d9d7c58 <https://github.com/symfony/symfony-docs/commit/d9d7c58ca41ae370545ae25f13857780c089f970>`_ #3444 Fix issue #3442 (ifdattic)
+- `9e2e64b <https://github.com/symfony/symfony-docs/commit/9e2e64b26a355416038b632b7eec89c7c14490cb>`_ #3427 Removed code references to Symfony Standard Distribution (danielcsgomes)
+- `26b8146 <https://github.com/symfony/symfony-docs/commit/26b8146188a3f8bedf2e681d40509b418c8e7ec0>`_ #3415 [#3334] the data_class option was not introduced in 2.4 (xabbuh)
+- `0b2a491 <https://github.com/symfony/symfony-docs/commit/0b2a49199752f60aa1bcc16d48f4c558160e852e>`_ #3414 add missing code-block directive (xabbuh)
+- `4988118 <https://github.com/symfony/symfony-docs/commit/4988118e127dc51d73e2518982c0a0f4ca9206f1>`_ #3432 [Reference][Form Types] Add "max_length" option in form type (nykopol)
+- `26a7b1b <https://github.com/symfony/symfony-docs/commit/26a7b1b80aa654c9293599743f9c0a38054eb4d3>`_ #3423 [Session Configuration] add clarifying notes on session save handler proxies (cordoval)
+
+Minor Documentation Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `1131247 <https://github.com/symfony/symfony-docs/commit/11312477437e5367da466727acdc89c97b8ed73a>`_ #3508 Add 'in XML' for additional clarity (ifdattic)
+- `a650b93 <https://github.com/symfony/symfony-docs/commit/a650b9364297aa5eaa5ffd3c018b3f0858d12238>`_ #3506 Nykopol overriden options (weaverryan)
+- `ab10035 <https://github.com/symfony/symfony-docs/commit/ab1003501de3e81bc48226b32b53156e2e7a573a>`_ #3505 replace Akamaï with Akamai (xabbuh)
+- `7f56c20 <https://github.com/symfony/symfony-docs/commit/7f56c201ea4cd9b1e7b7ed36ceb2046352a143f2>`_ #3501 [Security] Fix markup (tyx)
+- `80a90ba <https://github.com/symfony/symfony-docs/commit/80a90ba8b5c2eceeb2d80bb1386fb2620b8e0c6e>`_ #3500 Minimize horizontal scrolling in code blocks (improve readability) (ifdattic)
+- `e5bc4ea <https://github.com/symfony/symfony-docs/commit/e5bc4eafeab96b8b12070ce0435b8a77ee85c6c1>`_ #3498 Remove second empty data (xabbuh)
+- `d084d87 <https://github.com/symfony/symfony-docs/commit/d084d876e3ab961c92f2753c73b0a73a75ee7a8b>`_ #3485 [Cookbook][Assetic] Fix "javascripts" tag name typo (bicpi)
+- `3250aba <https://github.com/symfony/symfony-docs/commit/3250aba13ccf8662aa8e38cb624b3adeab0944bc>`_ #3481 Fix code block (minimise horizontal scrolling), typo in yaml (ifdattic)
+- `f285d93 <https://github.com/symfony/symfony-docs/commit/f285d930377d8cbaedccc3ad46853fa72ee6439d>`_ #3451 some language tweaks (AE, third-person perspective) (xabbuh)
+- `2b7e0f6 <https://github.com/symfony/symfony-docs/commit/2b7e0f6f2f9982e600918f447852a6f4c60966a1>`_ #3497 Fix highlighting (WouterJ)
+- `a535ae0 <https://github.com/symfony/symfony-docs/commit/a535ae0383a2a6715021681980877b0205dc3281>`_ #3471 Fixed `````versionadded````` inconsistencies in Symfony 2.3 (danielcsgomes)
+- `f077a8e <https://github.com/symfony/symfony-docs/commit/f077a8e71c4973e7775db8c9fb548a0866d21131>`_ #3465 change wording in versionadded example to be consistent with what we use... (xabbuh)
+- `f9f7548 <https://github.com/symfony/symfony-docs/commit/f9f7548c7a53e62564b30d7e945a9b52b3f358db>`_ #3462 Replace ... with etc (ifdattic)
+- `65efcc4 <https://github.com/symfony/symfony-docs/commit/65efcc4f64365acf5895597bb32e9b611f9bbfcd>`_ #3445 [Reference][Form Types] Add missing (but existing) options to "form" type (bicpi)
+- `1d1b91d <https://github.com/symfony/symfony-docs/commit/1d1b91d6cbd4479e85ff2fdbc2cbab4f7a9a778b>`_ #3431 [Config] add cautionary note on ini file loader limitation (cordoval)
+- `f2eaf9b <https://github.com/symfony/symfony-docs/commit/f2eaf9bbc5d3a73c83ef6e4ce1830bd3e277dcc0>`_ #3419 doctrine file upload example uses dir -- caution added (cordoval)
+- `72b53ad <https://github.com/symfony/symfony-docs/commit/72b53ad4312f74920568e39ebbddc2b3b8008797>`_ #3404 [#3276] Trying to further clarify the session storage directory details (weaverryan)
+- `67b7bbd <https://github.com/symfony/symfony-docs/commit/67b7bbda858337555b7404a17e6ead20d2144eff>`_ #3413 [Cookbook][Bundles] improve explanation of code block for bundle removal (cordoval)
+- `7c5a914 <https://github.com/symfony/symfony-docs/commit/7c5a9141d6dd716e692b27904190225be324f332>`_ #3369 Indicate that Group Sequence Providers can use YAML (karptonite)
+- `1e0311e <https://github.com/symfony/symfony-docs/commit/1e0311ef0124fda8ad0cb07f73a3a52ce3303f2b>`_ #3416 add empty_data option where required option is used (xabbuh)
+- `2be3f52 <https://github.com/symfony/symfony-docs/commit/2be3f52cf5178606e54826e0766f31ce110ee122>`_ #3422 [Cookbook][Custom Authentication Provider] add a note of warning for when forbidding anonymous users (cordoval)

components/dependency_injection/parameters.rst

@@ -25,6 +25,13 @@ and set a parameter in the container with::
 
     $container->setParameter('mailer.transport', 'sendmail');
 
+.. caution::
+
+    The used ``.`` notation is just a
+    :ref:`Symfony convention <service-naming-conventions>` to make parameters
+    easier to read. Parameters are just flat key-value elements, they can't be
+    organized into a nested array
+
 .. note::
 
     You can only set a parameter before the container is compiled. To learn
@@ -190,9 +197,9 @@ making the class of a service a parameter:
 Array Parameters
 ----------------
 
-Parameters do not need to be flat strings, they can also be arrays. For the XML
-format, you need to use the ``type="collection"`` attribute for all parameters that are
-arrays.
+Parameters do not need to be flat strings, they can also contain array values.
+For the XML format, you need to use the ``type="collection"`` attribute for
+all parameters that are arrays.
 
 .. configuration-block::
 

components/event_dispatcher/generic_event.rst

@@ -93,7 +93,7 @@ Filtering data::
 
     use Symfony\Component\EventDispatcher\GenericEvent;
 
-    $event = new GenericEvent($subject, array('data' => 'foo'));
+    $event = new GenericEvent($subject, array('data' => 'Foo'));
     $dispatcher->dispatch('foo', $event);
 
     echo $event['data'];
@@ -102,6 +102,6 @@ Filtering data::
     {
         public function filter(GenericEvent $event)
         {
-            strtolower($event['data']);
+            $event['data'] = strtolower($event['data']);
         }
     }

components/form/introduction.rst

@@ -181,8 +181,10 @@ to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension
     $defaultFormTheme = 'form_div_layout.html.twig';
 
     $vendorDir = realpath(__DIR__ . '/../vendor');
-    // the path to TwigBridge so Twig can locate the form_div_layout.html.twig file
-    $vendorTwigBridgeDir = $vendorDir . '/symfony/twig-bridge/Symfony/Bridge/Twig';
+    // the path to TwigBridge so Twig can locate the
+    // form_div_layout.html.twig file
+    $vendorTwigBridgeDir =
+        $vendorDir . '/symfony/twig-bridge/Symfony/Bridge/Twig';
     // the path to your other templates
     $viewsDir = realpath(__DIR__ . '/../views');
 
@@ -193,7 +195,9 @@ to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension
     $formEngine = new TwigRendererEngine(array($defaultFormTheme));
     $formEngine->setEnvironment($twig);
     // add the FormExtension to Twig
-    $twig->addExtension(new FormExtension(new TwigRenderer($formEngine, $csrfProvider)));
+    $twig->addExtension(
+        new FormExtension(new TwigRenderer($formEngine, $csrfProvider))
+    );
 
     // create your form factory as normal
     $formFactory = Forms::createFormFactoryBuilder()
@@ -307,7 +311,8 @@ Your integration with the Validation component will look something like this::
 
     $vendorDir = realpath(__DIR__ . '/../vendor');
     $vendorFormDir = $vendorDir . '/symfony/form/Symfony/Component/Form';
-    $vendorValidatorDir = $vendorDir . '/symfony/validator/Symfony/Component/Validator';
+    $vendorValidatorDir =
+        $vendorDir . '/symfony/validator/Symfony/Component/Validator';
 
     // create the validator - details will vary
     $validator = Validation::createValidator();

components/http_foundation/introduction.rst

@@ -262,7 +262,8 @@ If you need to get full access to parsed data from ``Accept``, ``Accept-Language
     }
 
     // accepts items are sorted by descending quality
-    $accepts = AcceptHeader::fromString($request->headers->get('Accept'))->all();
+    $accepts = AcceptHeader::fromString($request->headers->get('Accept'))
+        ->all();
 
 Accessing other Data
 ~~~~~~~~~~~~~~~~~~~~
@@ -286,8 +287,24 @@ PHP callable that is able to create an instance of your ``Request`` class::
 
     use Symfony\Component\HttpFoundation\Request;
 
-    Request::setFactory(function (array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), $content = null) {
-        return SpecialRequest::create($query, $request, $attributes, $cookies, $files, $server, $content);
+    Request::setFactory(function (
+        array $query = array(),
+        array $request = array(),
+        array $attributes = array(),
+        array $cookies = array(),
+        array $files = array(),
+        array $server = array(),
+        $content = null
+    ) {
+        return SpecialRequest::create(
+            $query,
+            $request,
+            $attributes,
+            $cookies,
+            $files,
+            $server,
+            $content
+        );
     });
 
     $request = Request::createFromGlobals();
@@ -458,7 +475,10 @@ abstracts the hard work behind a simple API::
 
     use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 
-    $d = $response->headers->makeDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'foo.pdf');
+    $d = $response->headers->makeDisposition(
+        ResponseHeaderBag::DISPOSITION_ATTACHMENT,
+        'foo.pdf'
+    );
 
     $response->headers->set('Content-Disposition', $d);
 
@@ -482,7 +502,10 @@ if it should::
 You can still set the ``Content-Type`` of the sent file, or change its ``Content-Disposition``::
 
     $response->headers->set('Content-Type', 'text/plain');
-    $response->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'filename.txt');
+    $response->setContentDisposition(
+        ResponseHeaderBag::DISPOSITION_ATTACHMENT,
+        'filename.txt'
+    );
 
 .. _component-http-foundation-json-response:
 

components/http_foundation/sessions.rst

@@ -28,7 +28,7 @@ Quick example::
 
     // retrieve messages
     foreach ($session->getFlashBag()->get('notice', array()) as $message) {
-        echo "<div class='flash-notice'>$message</div>";
+        echo '<div class="flash-notice">'.$message.'</div>';
     }
 
 .. note::
@@ -254,7 +254,7 @@ has a simple API
   Adds a flash message to the stack of specified type;
 
 * :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::set`:
-  Sets flashes by type; This method conveniently takes both singles messages as
+  Sets flashes by type; This method conveniently takes both single messages as
   a ``string`` or multiple messages in an ``array``.
 
 * :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::get`:
@@ -308,18 +308,18 @@ Simple, display one type of message::
 
     // display warnings
     foreach ($session->getFlashBag()->get('warning', array()) as $message) {
-        echo "<div class='flash-warning'>$message</div>";
+        echo '<div class="flash-warning">'.$message.'</div>';
     }
 
     // display errors
     foreach ($session->getFlashBag()->get('error', array()) as $message) {
-        echo "<div class='flash-error'>$message</div>";
+        echo '<div class="flash-error">'.$message.'</div>';
     }
 
 Compact method to process display all flashes at once::
 
     foreach ($session->getFlashBag()->all() as $type => $messages) {
         foreach ($messages as $message) {
-            echo "<div class='flash-$type'>$message</div>\n";
+            echo '<div class="flash-'.$type.'">'.$message.'</div>';
         }
     }

components/http_kernel/introduction.rst

@@ -603,6 +603,7 @@ a built-in ControllerResolver that can be used to create a working example::
     use Symfony\Component\HttpKernel\HttpKernel;
     use Symfony\Component\EventDispatcher\EventDispatcher;
     use Symfony\Component\HttpKernel\Controller\ControllerResolver;
+    use Symfony\Component\HttpKernel\EventListener\RouterListener;
     use Symfony\Component\Routing\RouteCollection;
     use Symfony\Component\Routing\Route;
     use Symfony\Component\Routing\Matcher\UrlMatcher;
@@ -611,7 +612,9 @@ a built-in ControllerResolver that can be used to create a working example::
     $routes = new RouteCollection();
     $routes->add('hello', new Route('/hello/{name}', array(
             '_controller' => function (Request $request) {
-                return new Response(sprintf("Hello %s", $request->get('name')));
+                return new Response(
+                    sprintf("Hello %s", $request->get('name'))
+                );
             }
         )
     ));
@@ -647,7 +650,7 @@ your controller).
    :align: center
 
 To execute a sub request, use ``HttpKernel::handle``, but change the second
-arguments as follows::
+argument as follows::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpKernel\HttpKernelInterface;