Merge branch 'master' of https://github.com/symfony/symfony-docs

Author: mdpatrick

book/controller.rst

@@ -313,6 +313,8 @@ the following guidelines in mind while you develop.
     the name of the route that was matched (e.g. ``hello``). Though not usually
     useful, this is equally available as a controller argument.
 
+.. _book-controller-request-argument:
+
 The ``Request`` as a Controller Argument
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

book/doctrine.rst

@@ -44,21 +44,21 @@ Configuring the Database
 
 Before you really begin, you'll need to configure your database connection
 information. By convention, this information is usually configured in an
-``app/config/parameters.ini`` file:
+``app/config/parameters.yml`` file:
 
-.. code-block:: ini
+.. code-block:: yaml
 
-    ;app/config/parameters.ini
-    [parameters]
-        database_driver   = pdo_mysql
-        database_host     = localhost
-        database_name     = test_project
-        database_user     = root
-        database_password = password
+    # app/config/parameters.yml
+    parameters:
+        database_driver:   pdo_mysql
+        database_host:     localhost
+        database_name:     test_project
+        database_user:     root
+        database_password: password
 
 .. note::
 
-    Defining the configuration via ``parameters.ini`` is just a convention.
+    Defining the configuration via ``parameters.yml`` is just a convention.
     The parameters defined in that file are referenced by the main configuration
     file when setting up Doctrine:
 
@@ -326,7 +326,7 @@ in your application. To do this, run:
     needed to *update* the database to where it should be. In other words, if you add
     a new property with mapping metadata to ``Product`` and run this task
     again, it will generate the "alter table" statement needed to add that
-    new column to the existing ``products`` table.
+    new column to the existing ``product`` table.
 
     An even better way to take advantage of this functionality is via
     :doc:`migrations</bundles/DoctrineMigrationsBundle/index>`, which allow you to
@@ -861,7 +861,7 @@ table, and ``product.category_id`` column, and new foreign key:
 
     This task should only be really used during development. For a more robust
     method of systematically updating your production database, read about
-    :doc:`Doctrine migrations</bundles/DoctrineFixturesBundle/index>`.
+    :doc:`Doctrine migrations</bundles/DoctrineMigrationsBundle/index>`.
 
 Saving Related Entities
 ~~~~~~~~~~~~~~~~~~~~~~~

book/forms.rst

@@ -598,6 +598,20 @@ the label, errors and HTML form widget of each field inside a ``div`` tag
 by default. In the :ref:`form-theming` section, you'll learn how the ``form_row``
 output can be customized on many different levels.
 
+.. tip::
+
+    You can access the current data of your form via ``form.vars.value``:
+    
+    .. configuration-block::
+
+        .. code-block:: jinja
+        
+            {{ form.vars.value.task }}
+
+        .. code-block:: html+php
+
+            <?php echo $view['form']->get('value')->getTask() ?>
+
 .. index::
    single: Forms; Rendering each field by hand
 
@@ -746,6 +760,8 @@ Placing the form logic into its own class means that the form can be easily
 reused elsewhere in your project. This is the best way to create forms, but
 the choice is ultimately up to you.
 
+.. _book-forms-data-class:
+
 .. sidebar:: Setting the ``data_class``
 
     Every form needs to know the name of the class that holds the underlying
@@ -936,9 +952,12 @@ and can be persisted to the database or used however you need.
 Embedding a Collection of Forms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can also embed a collection of forms into one form. This is done by
-using the ``collection`` field type. For more information, see the
-:doc:`collection field type reference</reference/forms/types/collection>`.
+You can also embed a collection of forms into one form (imagine a ``Category``
+form with many ``Product`` sub-forms). This is done by using the ``collection``
+field type.
+
+For more information see the ":doc:`/cookbook/form/form_collections`" cookbook
+entry and  the :ref:`collection</reference/forms/types/collection>` field type reference.
 
 .. index::
    single: Forms; Theming
@@ -1295,6 +1314,130 @@ section.
     The ``intention`` option is optional but greatly enhances the security of
     the generated token by making it different for each form.
 
+.. index:
+   single: Forms; With no class
+
+Using a Form without a Class
+----------------------------
+
+In most cases, a form is tied to an object, and the fields of the form get
+and store their data on the properties of that object. This is exactly what
+you've seen so far in this chapter with the `Task` class.
+
+But sometimes, you may just want to use a form without a class, and get back
+an array of the submitted data. This is actually really easy::
+
+    // make sure you've imported the Request namespace above the class
+    use Symfony\Component\HttpFoundation\Request
+    // ...
+
+    public function contactAction(Request $request)
+    {
+        $defaultData = array('message' => 'Type your message here');
+        $form = $this->createFormBuilder($defaultData)
+            ->add('name', 'text')
+            ->add('email', 'email')
+            ->add('message', 'textarea')
+            ->getForm();
+        
+            if ($request->getMethod() == 'POST') {
+                $form->bindRequest($request);
+
+                // data is an array with "name", "email", and "message" keys
+                $data = $form->getData();
+            }
+        
+        // ... render the form
+    }
+
+By default, a form actually assumes that you want to work with arrays of
+data, instead of an object. There are exactly two ways that you can change
+this behavior and tie the form to an object instead:
+
+1. Pass an object when creating the form (as the first argument to ``createFormBuilder``
+   or the second argument to ``createForm``);
+
+2. Declare the ``data_class`` option on your form.
+
+If you *don't* do either of these, then the form will return the data as
+an array. In this example, since ``$defaultData`` is not an object (and
+no ``data_class`` option is set), ``$form->getData()`` ultimately returns
+an array.
+
+.. tip::
+
+    You can also access POST values (in this case "name") directly through 
+    the request object, like so:
+
+    .. code-block:: php
+
+        $this->get('request')->request->get('name');
+
+    Be advised, however, that in most cases using the getData() method is 
+    a better choice, since it returns the data (usually an object) after
+    it's been transformed by the form framework.
+
+Adding Validation
+~~~~~~~~~~~~~~~~~
+
+The only missing piece is validation. Usually, when you call ``$form->isValid()``,
+the object is validated by reading the constraints that you applied to that
+class. But without a class, how can you add constraints to the data of your
+form?
+
+The answer is to setup the constraints yourself, and pass them into your
+form. The overall approach is covered a bit more in the :ref:`validation chapter<book-validation-raw-values>`,
+but here's a short example::
+
+    // import the namespaces above your controller class
+    use Symfony\Component\Validator\Constraints\Email;
+    use Symfony\Component\Validator\Constraints\MinLength;
+    use Symfony\Component\Validator\Constraints\Collection;
+
+    $collectionConstraint = new Collection(array(
+        'name' => new MinLength(5),
+        'email' => new Email(array('message' => 'Invalid email address')),
+    ));
+
+    // create a form, no default values, pass in the constraint option
+    $form = $this->createFormBuilder(null, array(
+        'validation_constraint' => $collectionConstraint,
+    ))->add('email', 'email')
+        // ...
+    ;
+
+Now, when you call `$form->isValid()`, the constraints setup here are run
+against your form's data. If you're using a form class, override the ``getDefaultOptions``
+method to specify the option::
+
+    namespace Acme\TaskBundle\Form\Type;
+
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\FormBuilder;
+    use Symfony\Component\Validator\Constraints\Email;
+    use Symfony\Component\Validator\Constraints\MinLength;
+    use Symfony\Component\Validator\Constraints\Collection;
+
+    class ContactType extends AbstractType
+    {
+        // ...
+
+        public function getDefaultOptions(array $options)
+        {
+            $collectionConstraint = new Collection(array(
+                'name' => new MinLength(5),
+                'email' => new Email(array('message' => 'Invalid email address')),
+            ));
+        
+            $options['validation_constraint'] = $collectionConstraint;
+        }
+    }
+
+Now, you have the flexibility to create forms - with validation - that return
+an array of data, instead of an object. In most cases, it's better - and
+certainly more robust - to bind your form to an object. But for simple forms,
+this is a great approach. 
+
 Final Thoughts
 --------------
 
@@ -1320,6 +1463,7 @@ Learn more from the Cookbook
 * :doc:`File Field Reference </reference/forms/types/file>`
 * :doc:`Creating Custom Field Types </cookbook/form/create_custom_field_type>`
 * :doc:`/cookbook/form/form_customization`
+* :doc:`/cookbook/form/dynamic_form_generation`
 
 .. _`Symfony2 Form Component`: https://github.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php

book/http_cache.rst

@@ -396,7 +396,7 @@ The HTTP specification defines two caching models:
   until the cached version reaches its expiration time and becomes "stale".
 
 * When pages are really dynamic (i.e. their representation changes often),
-  the `validation model`_ model is often necessary. With this model, the
+  the `validation model`_ is often necessary. With this model, the
   cache stores the response, but asks the server on each request whether
   or not the cached response is still valid. The application uses a unique
   response identifier (the ``Etag`` header) and/or a timestamp (the ``Last-Modified``
@@ -846,7 +846,7 @@ independent of the rest of the page.
 
 In this example, we've given the full-page cache a lifetime of ten minutes.
 Next, let's include the news ticker in the template by embedding an action.
-This is done via the ``render`` helper (See `templating-embedding-controller`
+This is done via the ``render`` helper (See :ref:`templating-embedding-controller`
 for more details).
 
 As the embedded content comes from another page (or controller for that
@@ -939,9 +939,9 @@ the ``_internal`` route:
 
     Since this route allows all actions to be accessed via a URL, you might
     want to protect it by using the Symfony2 firewall feature (by allowing
-    access to your reverse proxy's IP range). See the 
-    :doc:`Security Configuration Reference </reference/configuration/security>` 
-    for more information on how to do this.
+    access to your reverse proxy's IP range). See the :ref:`Securing by IP<book-security-securing-ip>` 
+    section of the :doc:`Security Chapter </book/security>` for more information 
+    on how to do this.
 
 One great advantage of this caching strategy is that you can make your
 application as dynamic as needed and at the same time, hit the application as
@@ -983,8 +983,9 @@ too far away in the future.
 
 .. note::
 
-    It's also because there is no invalidation mechanism that you can use any
-    reverse proxy without changing anything in your application code.
+    Since invalidation is a topic specific to each type of reverse proxy,
+    if you don't worry about invalidation, you can switch between reverse
+    proxies without changing anything in your application code.
 
 Actually, all reverse proxies provide ways to purge cached data, but you
 should avoid them as much as possible. The most standard way is to purge the
@@ -1003,7 +1004,7 @@ Here is how you can configure the Symfony2 reverse proxy to support the
             }
 
             $response = new Response();
-            if (!$this->store->purge($request->getUri())) {
+            if (!$this->getStore()->purge($request->getUri())) {
                 $response->setStatusCode(404, 'Not purged');
             } else {
                 $response->setStatusCode(200, 'Purged');

book/internals.rst

@@ -380,6 +380,8 @@ and set a new ``Exception`` object, or do nothing:
 .. index::
    single: Event Dispatcher
 
+.. _`book-internals-event-dispatcher`:
+
 The Event Dispatcher
 --------------------
 
@@ -403,7 +405,7 @@ Take a simple example from the `Symfony2 HttpKernel component`_. Once a
 ``Response`` object has been created, it may be useful to allow other elements
 in the system to modify it (e.g. add some cache headers) before it's actually
 used. To make this possible, the Symfony2 kernel throws an event -
-``kernel.response``. Here's how it work:
+``kernel.response``. Here's how it works:
 
 * A *listener* (PHP object) tells a central *dispatcher* object that it wants
   to listen to the ``kernel.response`` event;
@@ -748,8 +750,16 @@ can be the way to go, especially for optional dependencies.
 
     If you use dependency injection like we did in the two examples above, you
     can then use the `Symfony2 Dependency Injection component`_ to elegantly
-    manage these objects.
+    manage the injection of the ``event_dispatcher`` service for these objects.
+
+        .. code-block:: yaml
 
+            # src/Acme/HelloBundle/Resources/config/services.yml
+            services:
+                foo_service:
+                    class: Acme/HelloBundle/Foo/FooService
+                    arguments: [@event_dispatcher]
+            
 .. index::
    single: Event Dispatcher; Event subscribers
 
@@ -814,6 +824,12 @@ returned by the ``getSubscribedEvents`` method. This method returns an array
 indexed by event names and whose values are either the method name to call or
 an array composed of the method name to call and a priority.
 
+.. tip::
+
+    If you use the Symfony2 MVC framework, subscribers can be registered via
+    your :ref:`configuration <dic-tags-kernel-event-subscriber>`. As an added
+    bonus, the subscriber objects are instantiated only when needed.
+
 .. index::
    single: Event Dispatcher; Stopping event flow
 

book/page_creation.rst

@@ -721,7 +721,7 @@ format you prefer:
 
         # app/config/config.yml
         imports:
-            - { resource: parameters.ini }
+            - { resource: parameters.yml }
             - { resource: security.yml }
         
         framework:
@@ -747,7 +747,7 @@ format you prefer:
 
         <!-- app/config/config.xml -->
         <imports>
-            <import resource="parameters.ini" />
+            <import resource="parameters.yml" />
             <import resource="security.yml" />
         </imports>
         
@@ -769,7 +769,7 @@ format you prefer:
 
     .. code-block:: php
 
-        $this->import('parameters.ini');
+        $this->import('parameters.yml');
         $this->import('security.yml');
 
         $container->loadFromExtension('framework', array(

book/routing.rst

@@ -1083,6 +1083,18 @@ that route. With this information, any URL can easily be generated:
 
 In an upcoming section, you'll learn how to generate URLs from inside templates.
 
+.. tip::
+
+    If the frontend of your application uses AJAX requests, you might want
+    to be able to generate URLs in JavaScript based on your routing configuration.
+    By using the `FOSJsRoutingBundle`_, you can do exactly that:
+    
+    .. code-block:: javascript
+    
+        var url = Routing.generate('blog_show', { "slug": 'my-blog-post});
+
+    For more information, see the documentation for that bundle.
+
 .. index::
    single: Routing; Absolute URLs
 
@@ -1172,3 +1184,5 @@ Learn more from the Cookbook
 ----------------------------
 
 * :doc:`/cookbook/routing/scheme`
+
+.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle