Merge branch '2.3'

Author: weaverryan

book/doctrine.rst

@@ -960,7 +960,7 @@ To relate the ``Category`` and ``Product`` entities, start by creating a
             <entity name="Acme\StoreBundle\Entity\Category">
                 <!-- ... -->
                 <one-to-many field="products"
-                    target-entity="product"
+                    target-entity="Product"
                     mapped-by="category"
                 />
 
@@ -988,7 +988,7 @@ makes sense in the application for each ``Category`` to hold an array of
 .. tip::
 
    The targetEntity value in the decorator used above can reference any entity
-   with a valid namespace, not just entities defined in the same class. To
+   with a valid namespace, not just entities defined in the same namespace. To
    relate to an entity defined in a different class or bundle, enter a full
    namespace as the targetEntity.
 
@@ -1038,7 +1038,8 @@ object, you'll want to add a ``$category`` property to the ``Product`` class:
             <entity name="Acme\StoreBundle\Entity\Product">
                 <!-- ... -->
                 <many-to-one field="category"
-                    target-entity="products"
+                    target-entity="Category"
+                    inversed-by="products"
                     join-column="category"
                 >
                     <join-column
@@ -1205,14 +1206,14 @@ to the given ``Category`` object via their ``category_id`` value.
 
     The proxy classes are generated by Doctrine and stored in the cache directory.
     And though you'll probably never even notice that your ``$category``
-    object is actually a proxy object, it's important to keep in mind.
+    object is actually a proxy object, it's important to keep it in mind.
 
     In the next section, when you retrieve the product and category data
     all at once (via a *join*), Doctrine will return the *true* ``Category``
     object, since nothing needs to be lazily loaded.
 
-Joining to Related Records
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Joining Related Records
+~~~~~~~~~~~~~~~~~~~~~~~
 
 In the above examples, two queries were made - one for the original object
 (e.g. a ``Category``) and one for the related object(s) (e.g. the ``Product``
@@ -1304,7 +1305,7 @@ callbacks. This is not necessary if you're using YAML or XML for your mapping:
     }
 
 Now, you can tell Doctrine to execute a method on any of the available lifecycle
-events. For example, suppose you want to set a ``created`` date column to
+events. For example, suppose you want to set a ``createdAt`` date column to
 the current date, only when the entity is first persisted (i.e. inserted):
 
 .. configuration-block::
@@ -1314,9 +1315,9 @@ the current date, only when the entity is first persisted (i.e. inserted):
         /**
          * @ORM\PrePersist
          */
-        public function setCreatedValue()
+        public function setCreatedAtValue()
         {
-            $this->created = new \DateTime();
+            $this->createdAt = new \DateTime();
         }
 
     .. code-block:: yaml
@@ -1326,7 +1327,7 @@ the current date, only when the entity is first persisted (i.e. inserted):
             type: entity
             # ...
             lifecycleCallbacks:
-                prePersist: [setCreatedValue]
+                prePersist: [setCreatedAtValue]
 
     .. code-block:: xml
 
@@ -1339,18 +1340,18 @@ the current date, only when the entity is first persisted (i.e. inserted):
                     <!-- ... -->
                     <lifecycle-callbacks>
                         <lifecycle-callback type="prePersist"
-                            method="setCreatedValue" />
+                            method="setCreatedAtValue" />
                     </lifecycle-callbacks>
             </entity>
         </doctrine-mapping>
 
 .. note::
 
-    The above example assumes that you've created and mapped a ``created``
+    The above example assumes that you've created and mapped a ``createdAt``
     property (not shown here).
 
 Now, right before the entity is first persisted, Doctrine will automatically
-call this method and the ``created`` field will be set to the current date.
+call this method and the ``createdAt`` field will be set to the current date.
 
 This can be repeated for any of the other lifecycle events, which include:
 
@@ -1368,7 +1369,7 @@ in general, see Doctrine's `Lifecycle Events documentation`_
 
 .. sidebar:: Lifecycle Callbacks and Event Listeners
 
-    Notice that the ``setCreatedValue()`` method receives no arguments. This
+    Notice that the ``setCreatedAtValue()`` method receives no arguments. This
     is always the case for lifecycle callbacks and is intentional: lifecycle
     callbacks should be simple methods that are concerned with internally
     transforming data in the entity (e.g. setting a created/updated field,

book/forms.rst

@@ -654,6 +654,7 @@ guess from the validation rules that both the ``task`` field is a normal
         $form = $this->createFormBuilder($task)
             ->add('task')
             ->add('dueDate', null, array('widget' => 'single_text'))
+            ->add('save', 'submit')
             ->getForm();
     }
 
@@ -918,6 +919,7 @@ ways. If you build your form in the controller, you can use ``setAction()`` and
         ->setMethod('GET')
         ->add('task', 'text')
         ->add('dueDate', 'date')
+        ->add('save', 'submit')
         ->getForm();
 
 .. note::
@@ -991,8 +993,9 @@ that will house the logic for building the task form::
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('task');
-            $builder->add('dueDate', null, array('widget' => 'single_text'));
+            $builder->add('task')
+                ->add('dueDate', null, array('widget' => 'single_text'))
+                ->add('save', 'submit');
         }
 
         public function getName()
@@ -1057,8 +1060,9 @@ the choice is ultimately up to you.
 
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('task');
-            $builder->add('dueDate', null, array('mapped' => false));
+            $builder->add('task')
+                ->add('dueDate', null, array('mapped' => false))
+                ->add('save', 'submit');
         }
 
     Additionally, if there are any fields on the form that aren't included in
@@ -1731,6 +1735,7 @@ an array of the submitted data. This is actually really easy::
             ->add('name', 'text')
             ->add('email', 'email')
             ->add('message', 'textarea')
+            ->add('send', 'submit')
             ->getForm();
 
         $form->handleRequest($request);

book/http_fundamentals.rst

@@ -430,7 +430,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
     .. code-block:: xml
 
         <route id="contact" path="/contact">
-            <default key="_controller">AcmeBlogBundle:Main:contact</default>
+            <default key="_controller">AcmeDemoBundle:Main:contact</default>
         </route>
 
     .. code-block:: php
@@ -441,7 +441,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
 
         $collection = new RouteCollection();
         $collection->add('contact', new Route('/contact', array(
-            '_controller' => 'AcmeBlogBundle:Main:contact',
+            '_controller' => 'AcmeDemoBundle:Main:contact',
         )));
 
         return $collection;

book/installation.rst

@@ -127,12 +127,6 @@ All public files and the front controller that handles incoming requests in
 a Symfony2 application live in the ``Symfony/web/`` directory. So, assuming
 you unpacked the archive into your web server's or virtual host's document root,
 your application's URLs will start with ``http://localhost/Symfony/web/``.
-To get nice and short URLs you should point the document root of your web
-server or virtual host to the ``Symfony/web/`` directory. Though this is not
-required for development it is recommended when your application goes into
-production as all system and configuration files become inaccessible to clients.
-For information on configuring your specific web server document root, see
-the following documentation: `Apache`_ | `Nginx`_ .
 
 .. note::
 

book/page_creation.rst

@@ -22,6 +22,42 @@ HTTP response.
 Symfony2 follows this philosophy and provides you with tools and conventions
 to keep your application organized as it grows in users and complexity.
 
+.. index::
+   single: Page creation; Environments & Front Controllers
+
+.. _page-creation-environments:
+
+Environments & Front Controllers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every Symfony application runs within an :term:`environment`. An environment
+is a specific set of configuration and loaded bundles, represented by a string.
+The same application can be run with different configurations by running the
+application in different environments. Symfony2 comes with three environments
+defined — ``dev``, ``test`` and ``prod`` — but you can create your own as well.
+
+Environments are useful by allowing a single application to have a dev environment
+built for debugging and a production environment optimized for speed. You might
+also load specific bundles based on the selected environment. For example,
+Symfony2 comes with the WebProfilerBundle (described below), enabled only
+in the ``dev`` and ``test`` environments.
+
+Symfony2 comes with two web-accessible front controllers: ``app_dev.php`` 
+provides the ``dev`` environment, and ``app.php`` provides the ``prod`` environment.
+All web accesses to Symfony2 normally go through one of these front controllers.
+(The ``test`` environment is normally only used when running unit tests, and so 
+doesn't have a dedicated front controller. The console tool also provides a
+front controller that can be used with any environment.)
+
+When the front controller initializes the kernel, it provides two parameters:
+the environment, and also whether the kernel should run in debug mode.
+To make your application respond faster, Symfony2 maintains a cache under the
+``app/cache/`` directory. When in debug mode is enabled (such as ``app_dev.php``
+does by default), this cache is flushed automatically whenever you make changes
+to any code or configuration. When running in debug mode, Symfony2 runs
+slower, but your changes are reflected without having to manually clear the
+cache.
+
 .. index::
    single: Page creation; Example
 

book/propel.rst

@@ -353,7 +353,7 @@ Create the classes:
 
     $ php app/console propel:model:build
 
-Assuming you have products in your database, you don't want lose them. Thanks to
+Assuming you have products in your database, you don't want to lose them. Thanks to
 migrations, Propel will be able to update your database without losing existing
 data.
 
@@ -362,7 +362,7 @@ data.
     $ php app/console propel:migration:generate-diff
     $ php app/console propel:migration:migrate
 
-Your database has been updated, you can continue to write your application.
+Your database has been updated, you can continue writing your application.
 
 Saving Related Objects
 ~~~~~~~~~~~~~~~~~~~~~~

book/templating.rst

@@ -6,7 +6,7 @@ Creating and using Templates
 
 As you know, the :doc:`controller </book/controller>` is responsible for
 handling each request that comes into a Symfony2 application. In reality,
-the controller delegates the most of the heavy work to other places so that
+the controller delegates most of the heavy work to other places so that
 code can be tested and reused. When a controller needs to generate HTML,
 CSS or any other content, it hands the work off to the templating engine.
 In this chapter, you'll learn how to write powerful templates that can be
@@ -204,10 +204,10 @@ First, build a base layout file:
             <body>
                 <div id="sidebar">
                     {% block sidebar %}
-                    <ul>
-                        <li><a href="/">Home</a></li>
-                        <li><a href="/blog">Blog</a></li>
-                    </ul>
+                        <ul>
+                              <li><a href="/">Home</a></li>
+                              <li><a href="/blog">Blog</a></li>
+                        </ul>
                     {% endblock %}
                 </div>
 
@@ -561,8 +561,10 @@ Including this template from any other template is simple:
 
 The template is included using the ``{{ include() }}`` function. Notice that the
 template name follows the same typical convention. The ``articleDetails.html.twig``
-template uses an ``article`` variable. This is passed in by the ``list.html.twig``
-template using the ``with`` command.
+template uses an ``article`` variable, which we pass to it. In this case,
+you could avoid doing this entirely, as all of the variables available in
+``list.html.twig`` are also available in ``articleDetails.html.twig`` (unless
+you set `with_context`_ to false).
 
 .. tip::
 
@@ -571,8 +573,8 @@ template using the ``with`` command.
     elements, it would look like this: ``{'foo': foo, 'bar': bar}``.
 
 .. versionadded:: 2.2
-    The ``include()`` function is a new Twig feature that's available in
-    Symfony 2.2. Prior, the ``{% include %}`` tag was used.
+    The `include() function`_ is a new Twig feature that's available in Symfony
+    2.2. Prior, the `{% include %} tag`_ tag was used.
 
 .. index::
    single: Templating; Embedding action
@@ -1391,8 +1393,6 @@ in a JavaScript string, use the ``js`` context:
 .. index::
    single: Templating; Formats
 
-.. _template-formats:
-
 Debugging
 ---------
 
@@ -1434,6 +1434,8 @@ console command:
     # or using the bundle name:
     $ php app/console twig:lint @AcmeArticleBundle
 
+.. _template-formats:
+
 Template Formats
 ----------------
 
@@ -1529,3 +1531,6 @@ Learn more from the Cookbook
 .. _`filters`: http://twig.sensiolabs.org/doc/filters/index.html
 .. _`add your own extensions`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
 .. _`hinclude.js`: http://mnot.github.com/hinclude/
+.. _`with_context`: http://twig.sensiolabs.org/doc/functions/include.html
+.. _`include() function`: http://twig.sensiolabs.org/doc/functions/include.html
+.. _`{% include %} tag`: http://twig.sensiolabs.org/doc/tags/include.html

book/testing.rst

@@ -544,8 +544,7 @@ narrow down your node selection by chaining the method calls::
 
     $crawler
         ->filter('h1')
-        ->reduce(function ($node, $i)
-        {
+        ->reduce(function ($node, $i) {
             if (!$node->getAttribute('class')) {
                 return false;
             }

components/dependency_injection/advanced.rst

@@ -66,7 +66,7 @@ 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 the ``request``
+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>`.

components/event_dispatcher/introduction.rst

@@ -20,7 +20,7 @@ or after a method is executed, without interfering with other plugins. This is
 not an easy problem to solve with single inheritance, and multiple inheritance
 (were it possible with PHP) has its own drawbacks.
 
-The Symfony2 Event Dispatcher component implements the `Observer`_ pattern in
+The Symfony2 Event Dispatcher component implements the `Mediator`_ pattern in
 a simple and effective way to make all these things possible and to make your
 projects truly extensible.
 
@@ -588,7 +588,7 @@ part of the listener's processing logic::
         }
     }
 
-.. _Observer: http://en.wikipedia.org/wiki/Observer_pattern
+.. _Mediator: http://en.wikipedia.org/wiki/Mediator_pattern
 .. _Closures: http://php.net/manual/en/functions.anonymous.php
 .. _PHP callable: http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback
 .. _Packagist: https://packagist.org/packages/symfony/event-dispatcher