-
-
Notifications
You must be signed in to change notification settings - Fork 21
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add new docs for the event manager project. #5
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,10 +1,22 @@ | ||
Event Manager Documentation | ||
=========================== | ||
|
||
Welcome to the Doctrine Event Manager Library documentation. | ||
The Doctrine Event Manager documentation is a reference guide to everything you need | ||
to know about the project. | ||
|
||
.. toctree:: | ||
:depth: 2 | ||
:glob: | ||
Getting Help | ||
------------ | ||
|
||
* | ||
If this documentation is not helping to answer questions you have about the | ||
Doctrine DBAL, don't panic. You can get help from different sources: | ||
|
||
- Gitter chat room `#doctrine/event-manager <https://gitter.im/doctrine/event-manager>`_ | ||
- On `Stack Overflow <http://stackoverflow.com/questions/tagged/doctrine-event-manager>`_ | ||
- The `Doctrine Mailing List <http://groups.google.com/group/doctrine-user>`_ | ||
- Report a bug on `GitHub <https://github.com/doctrine/event-manager/issues>`_. | ||
|
||
Getting Started | ||
--------------- | ||
|
||
The best way to get started is with the :doc:`Introduction <reference/index#introduction>` section | ||
in the documentation. Use the sidebar to browse other documentation for the Doctrine Event Manager. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,133 @@ | ||
Introduction | ||
============ | ||
|
||
The Doctrine Event Manager is a simple event system used by the various Doctrine projects. It was originally built | ||
for the DBAL and ORM but over time other projects adopted it and now it is available as a standalone library. | ||
|
||
Installation | ||
============ | ||
|
||
The library can easily be installed with composer. | ||
|
||
.. code-block:: sh | ||
|
||
$ composer require doctrine/event-manager | ||
|
||
Setup | ||
===== | ||
|
||
The event system is controlled by the ``Doctrine\Common\EventManager`` class. | ||
|
||
.. code-block:: php | ||
|
||
use Doctrine\Common\EventManager; | ||
|
||
$eventManager = new EventManager(); | ||
|
||
Listeners | ||
========= | ||
|
||
Now you are ready to listen for events. Here is an exmaple of a custom event listener named ``TestEvent``. | ||
|
||
.. code-block:: php | ||
|
||
use Doctrine\Common\EventArgs; | ||
use Doctrine\Common\EventManager; | ||
|
||
final class TestEvent | ||
{ | ||
public const preFoo = 'preFoo'; | ||
public const postFoo = 'postFoo'; | ||
|
||
/** @var EventManager */ | ||
private $eventManager; | ||
|
||
/** @var bool */ | ||
public $preFooInvoked = false; | ||
|
||
/** @var bool */ | ||
public $postFooInvoked = false; | ||
|
||
public function __construct(EventManager $eventManager) | ||
{ | ||
$eventManager->addEventListener([self::preFoo, self::postFoo], $this); | ||
} | ||
|
||
public function preFoo(EventArgs $eventArgs) : void | ||
{ | ||
$this->preFooInvoked = true; | ||
} | ||
|
||
public function postFoo(EventArgs $eventArgs) : void | ||
{ | ||
$this->postFooInvoked = true; | ||
} | ||
} | ||
|
||
// Create a new instance | ||
$testEvent = new TestEvent($eventManager); | ||
|
||
Dispatching Events | ||
================== | ||
|
||
Now you can dispatch events with the ``dispatchEvent()`` method. | ||
|
||
.. code-block:: php | ||
|
||
$eventManager->dispatchEvent(TestEvent::preFoo); | ||
$eventManager->dispatchEvent(TestEvent::postFoo); | ||
|
||
Removing Event Listeners | ||
======================== | ||
|
||
You can easily remove a listener with the ``removeEventListener()`` method. | ||
|
||
.. code-block:: php | ||
|
||
$eventManager->removeEventListener([TestEvent::preFoo, TestEvent::postFoo], $testEvent); | ||
|
||
Event Subscribers | ||
================= | ||
|
||
The Doctrine event system also has a simple concept of event subscribers. We can define a simple ``TestEventSubscriber`` class which implements the ``Doctrine\Common\EventSubscriber`` interface and implements a ``getSubscribedEvents()`` method which returns an array of events it should be subscribed to. | ||
|
||
.. code-block:: php | ||
|
||
use Doctrine\Common\EventSubscriber; | ||
|
||
final class TestEventSubscriber implements EventSubscriber | ||
{ | ||
/** @var bool */ | ||
public $preFooInvoked = false; | ||
|
||
public function preFoo() : void | ||
{ | ||
$this->preFooInvoked = true; | ||
} | ||
|
||
public function getSubscribedEvents() : array | ||
{ | ||
return [TestEvent::preFoo]; | ||
} | ||
} | ||
|
||
$eventSubscriber = new TestEventSubscriber(); | ||
$eventManager->addEventSubscriber($eventSubscriber); | ||
|
||
.. note:: | ||
|
||
The array returned by the ``getSubscribedEvents()`` method is a simple array with the values being the event names. The subscriber must have a method that is named exactly like the event. | ||
|
||
Now when you dispatch an event, any event subscribers will be notified of that event. | ||
|
||
.. code-block:: php | ||
|
||
$eventManager->dispatchEvent(TestEvent::preFoo); | ||
|
||
Now you can check the ``preFooInvoked`` property to see if the event subscriber was notified of the event: | ||
|
||
.. code-block:: php | ||
|
||
if ($eventSubscriber->preFooInvoked) { | ||
// the preFoo method was invoked | ||
} |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
.. toctree:: | ||
:depth: 3 | ||
|
||
reference/index |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This comment was marked as off-topic.
Sorry, something went wrong.
This comment was marked as off-topic.
Sorry, something went wrong.