Permalink
Browse files

Merge branch '2.0' into 2.1

Conflicts:
	cookbook/doctrine/event_listeners_subscribers.rst
  • Loading branch information...
2 parents 6658c97 + aa68789 commit cf6cbafc246fa54f8518e199e489a3cbe3e5973b @weaverryan weaverryan committed Mar 30, 2013
View
@@ -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',
@@ -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;
@@ -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();
+
@@ -317,6 +317,8 @@ the ``getOrder`` method::
.. index::
single: Event Dispatcher; Event subscribers
+.. _event_dispatcher-using-event-subscribers:
+
Using Event Subscribers
~~~~~~~~~~~~~~~~~~~~~~~
View
@@ -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
@@ -10,4 +10,5 @@ Contributing Code
tests
standards
conventions
+ git
license
@@ -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:
View
@@ -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**
@@ -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
Oops, something went wrong.

0 comments on commit cf6cbaf

Please sign in to comment.