Merge branch '2.0' into 2.1

Conflicts:
	cookbook/doctrine/event_listeners_subscribers.rst

Author: weaverryan

book/testing.rst

@@ -354,14 +354,6 @@ or perform more complex requests::
         'image/jpeg',
         123
     );
-    // or
-    $photo = array(
-        'tmp_name' => '/path/to/photo.jpg',
-        'name'     => 'photo.jpg',
-        'type'     => 'image/jpeg',
-        'size'     => 123,
-        'error'    => UPLOAD_ERR_OK
-    );
     $client->request(
         'POST',
         '/submit',

components/console/introduction.rst

@@ -85,8 +85,8 @@ You also need to create the file to run at the command line which creates
 an ``Application`` and adds commands to it::
 
     #!/usr/bin/env php
-    # app/console
     <?php
+    // app/console
 
     use Acme\DemoBundle\Command\GreetCommand;
     use Symfony\Component\Console\Application;

components/console/single_command_tool.rst

@@ -43,7 +43,32 @@ it is possible to remove this need by extending the application::
 
             return $defaultCommands;
         }
+
+        /**
+         * Overridden so that the application doesn't expect the command
+         * name to be the first argument.
+         */
+        public function getDefinition()
+        {
+            $inputDefinition = parent::getDefinition();
+            // clear out the normal first argument, which is the command name
+            $inputDefinition->setArguments();
+
+            return $inputDefinition;
+        }
     }
 
 When calling your console script, the command `MyCommand` will then always
 be used, without having to pass its name.
+
+You can also simplify how you execute the application::
+
+    #!/usr/bin/env php
+    <?php
+    // command.php
+
+    use Acme\Tool\MyApplication;
+
+    $application = new MyApplication();
+    $application->run();
+

components/event_dispatcher/introduction.rst

@@ -317,6 +317,8 @@ the ``getOrder`` method::
 .. index::
    single: Event Dispatcher; Event subscribers
 
+.. _event_dispatcher-using-event-subscribers:
+
 Using Event Subscribers
 ~~~~~~~~~~~~~~~~~~~~~~~
 

contributing/code/git.rst

@@ -0,0 +1,42 @@
+Git
+===
+
+This document explains some conventions and specificities in the way we manage
+the Symfony code with Git.
+
+Pull Requests
+-------------
+
+Whenever a pull request is merged, all the information contained in the pull
+request (including comments) is saved in the repository.
+
+You can easily spot pull request merges as the commit message always follows
+this pattern:
+
+.. block: text
+
+    merged branch USER_NAME/BRANCH_NAME (PR #1111)
+
+The PR reference allows you to have a look at the original pull request on
+Github: https://github.com/symfony/symfony/pull/1111. But all the information
+you can get on Github is also available from the repository itself.
+
+The merge commit message contains the original message from the author of the
+changes. Often, this can help understand what the changes were about and the
+reasoning behind the changes.
+
+Moreover, the full discussion that might have occurred back then is also
+stored as a Git note (before March 22 2013, the discussion was part of the
+main merge commit message). To get access to these notes, add this line to
+your ``.git/config`` file:
+
+.. block: text
+
+    fetch = +refs/notes/*:refs/notes/*
+
+After a fetch, getting the Github discussion for a commit is then a matter of
+adding ``--show-notes=github-comments`` to the ``git show`` command:
+
+.. block: text
+
+    git show HEAD --show-notes=github-comments

contributing/code/index.rst

@@ -10,4 +10,5 @@ Contributing Code
     tests
     standards
     conventions
+    git
     license

contributing/documentation/overview.rst

@@ -79,12 +79,23 @@ GitHub covers the topic of `pull requests`_ in detail.
     The Symfony2 documentation is licensed under a Creative Commons
     Attribution-Share Alike 3.0 Unported :doc:`License <license>`.
 
+You can also prefix the title of your pull request in a few cases:
+
+* ``[WIP]`` (Work in Progress) is used when you are not yet finished with your
+  pull request, but you would like it to be reviewed. The pull request won't
+  be merged until you say it is ready.
+
+* ``[WCM]`` (Waiting Code Merge) is used when you're documenting a new feature
+  or change that hasn't been accepted yet into the core code. The pull request
+  will not be merged until it is merged in the core code (or closed if the
+  change is rejected).
+
 .. _doc-contributing-pr-format:
 
 Pull Request Format
 ~~~~~~~~~~~~~~~~~~~
 
-Unless you're fixing some minor typos, the pull request description must**
+Unless you're fixing some minor typos, the pull request description **must**
 include the following checklist to ensure that contributions may be reviewed
 without needless feedback loops and that your contributions can be included
 into the documentation as quickly as possible:

contributing/map.rst.inc

@@ -6,6 +6,7 @@
   * :doc:`Tests </contributing/code/tests>`
   * :doc:`Coding Standards</contributing/code/standards>`
   * :doc:`Code Conventions</contributing/code/conventions>`
+  * :doc:`Git</contributing/code/git>`  
   * :doc:`License </contributing/code/license>`
 
 * **Documentation**

cookbook/doctrine/event_listeners_subscribers.rst

@@ -17,6 +17,8 @@ Doctrine defines two types of objects that can listen to Doctrine events:
 listeners and subscribers. Both are very similar, but listeners are a bit
 more straightforward. For more, see `The Event System`_ on Doctrine's website.
 
+The Doctrine website also explains all existing events that can be listened to.
+
 Configuring the Listener/Subscriber
 -----------------------------------
 
@@ -119,8 +121,8 @@ Creating the Listener Class
 ---------------------------
 
 In the previous example, a service ``my.listener`` was configured as a Doctrine
-listener on the event ``postPersist``. That class behind that service must have
-a ``postPersist`` method, which will be called when the event is thrown::
+listener on the event ``postPersist``. The class behind that service must have
+a ``postPersist`` method, which will be called when the event is dispatched::
 
     // src/Acme/SearchBundle/EventListener/SearchIndexer.php
     namespace Acme\SearchBundle\EventListener;
@@ -149,7 +151,63 @@ itself.
 One important thing to notice is that a listener will be listening for *all*
 entities in your application. So, if you're interested in only handling a
 specific type of entity (e.g. a ``Product`` entity but not a ``BlogPost``
-entity), you should check for the class name of the entity in your method
+entity), you should check for the entity's class type in your method
 (as shown above).
 
+Creating the Subscriber Class
+-----------------------------
+
+A doctrine event subscriber must implement the ``Doctrine\Common\EventSubscriber``
+interface and have an event method for each event it subscribes to::
+
+    // src/Acme/SearchBundle/EventListener/SearchIndexerSubscriber.php
+    namespace Acme\SearchBundle\EventListener;
+
+    use Doctrine\Common\EventSubscriber;
+    use Doctrine\ORM\Event\LifecycleEventArgs;
+    // for doctrine 2.4: Doctrine\Common\Persistence\Event\LifecycleEventArgs;
+    use Acme\StoreBundle\Entity\Product;
+
+    class SearchIndexerSubscriber implements EventSubscriber
+    {
+        public function getSubscribedEvents()
+        {
+            return array(
+                'postPersist',
+                'postUpdate',
+            );
+        }
+
+        public function postUpdate(LifecycleEventArgs $args)
+        {
+            $this->index($args);
+        }
+
+        public function postPersist(LifecycleEventArgs $args)
+        {
+            $this->index($args);
+        }
+
+        public function index(LifecycleEventArgs $args)
+        {
+            $entity = $args->getEntity();
+            $entityManager = $args->getEntityManager();
+
+            // perhaps you only want to act on some "Product" entity
+            if ($entity instanceof Product) {
+                // ... do something with the Product
+            }
+        }
+    }
+
+.. tip::
+
+    Doctrine event subscribers can not return a flexible array of methods to
+    call for the events like the :ref:`Symfony event subscriber <event_dispatcher-using-event-subscribers>`
+    can. Doctrine event subscribers must return a simple array of the event
+    names they subscribe to. Doctrine will then expect methods on the subscriber
+    with the same name as each subscribed event, just as when using an event listener.
+
+For a full reference, see chapter `The Event System`_ in the Doctrine documentation.
+
 .. _`The Event System`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html