Restructured components to allow multiple parts and added more docs #1242

Closed
wants to merge 1 commit into
from

Projects

None yet

2 participants

@ghost

Some components are far too complex to expect all documentation to fit in a single documents
so this commit splits the documentation in the same way as in the cookbook docs.

Split Http Foundation into two parts (request/response and sessions).
Split Dependency Injection into it's own folder to provide the basis of further documentation,
Added ContainerAwareEventDispatcher documentation.
Added GenericEvent documentation.

Drak Restructured components to allow multiple parts and added more docume…
…ntation.

Some components are far too complex to expect all documentation to fit in a single documents
so this commit splits the documentation in the same way as in the cookbook docs.

Split Http Foundation into two parts (request/response and sessions).
Added ContainerAwareEventDispatcher documentation.
Added GenericEvent documentation.
4737e85
@jalliot jalliot commented on the diff Apr 11, 2012
...nents/event_dispatcher/container_aware_dispatcher.rst
+Setup is straightforward by injecting a :class:`Symfony\Component\DependencyInjection\ContainerInterface`
+into the :class:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher`::
+
+ use Symfony\Component\DependencyInjection\ContainerBuilder;
+ use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
+
+ $container = new Container();
+ $dispatcher = new ContainerAwareEventDispatcher($container);
+
+Adding Listeners
+----------------
+
+The ``Container Aware Event Dispatcher`` can either load directly specified
+services, or services as defined by :class:`Symfony\Component\EventDispatcher\EventSubscriberInterface`.
+
+The following examples assume the DIC has been loaded with the relevent services.
@jalliot jalliot commented on the diff Apr 11, 2012
...nents/event_dispatcher/container_aware_dispatcher.rst
+~~~~~~~~~~~~~~~
+
+Connecting existing service definitions is done with the
+:method:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher::addListenerService`
+method where the ``$callback`` is an array of ``array($serviceId, $methodName)``::
+
+ $dispatcher->addListenerService($eventName, array('foo', 'logListener'));
+
+Adding Subscriber Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``EventSubscribers`` can be added using the
+:method:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher::addSubscriberService`
+method as follows::
+
+ $dispatcher->addSubscriberService('kernel, 'StoreSubscriber');
@jalliot
jalliot Apr 11, 2012

maybe precise that the second argument is the class name of the service

@jalliot

Maybe wait for symfony/symfony#3784 before merging the Generic Event doc ;)

@jalliot jalliot commented on the diff Apr 11, 2012
components/event_dispatcher/generic_event.rst
+The Generic Event Object
+========================
+
+.. versionadded:: 2.1
+ Added general purpose ``GenericEvent`` event class since Symfony 2.1
+
+The base ``Event`` class provided by the ``Event Dispatcher`` component is
+deliberately sparse to allow the creation of API specific event objects by
+inheritance using OOP. This allow for elegant and readable code in complex
+applications.
+
+However, for convenience, the ``Event Dispatcher`` component comes with a general
+purpose event class :class:`Symfony\Component\EventDispatcher\GenericEvent`
+for those who wish to use one event object throughout their application. Since
+it is suitable for most purposes out of the box, it avoids the need to
+create situation specific event objects suitable for less complex applications.
@jalliot
jalliot Apr 11, 2012

less -> more no?

@stof stof commented on the diff Apr 11, 2012
...nents/event_dispatcher/container_aware_dispatcher.rst
+.. index::
+ single: Event Dispatcher; Container Aware; Dependency Injection
+
+The Container Aware Event Dispatcher
+====================================
+
+Introduction
+------------
+
+The :class:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher` is
+a special event dispatcher implementation which is coupled to the Symfony2
+Dependency Injection Container Component (DIC). It allows DIC services to be
+specified as event listeners making the event dispatcher extremely powerful.
+
+Services are lazy loaded meaning the services attached as listeners will only be
+created if an event is dispatched that requires those listeners.
@stof
stof Apr 11, 2012

you need to document somewhere that these services must be public ones

@ghost
ghost Apr 12, 2012

Good point, done.

@stof stof commented on the diff Apr 11, 2012
...nents/event_dispatcher/container_aware_dispatcher.rst
+Dependency Injection Container Component (DIC). It allows DIC services to be
+specified as event listeners making the event dispatcher extremely powerful.
+
+Services are lazy loaded meaning the services attached as listeners will only be
+created if an event is dispatched that requires those listeners.
+
+Setup
+-----
+
+Setup is straightforward by injecting a :class:`Symfony\Component\DependencyInjection\ContainerInterface`
+into the :class:`Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher`::
+
+ use Symfony\Component\DependencyInjection\ContainerBuilder;
+ use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
+
+ $container = new Container();
@stof
stof Apr 11, 2012

your use statement is about ContainerBuilder

@ghost
ghost Apr 12, 2012

Well stoffed :-)

@stof stof commented on the diff Apr 11, 2012
...nents/event_dispatcher/container_aware_dispatcher.rst
@@ -0,0 +1,87 @@
+.. index::
+ single: Event Dispatcher; Container Aware; Dependency Injection
+
+The Container Aware Event Dispatcher
+====================================
+
+Introduction
@stof
stof Apr 11, 2012

you need a versionadded note saying it was moved to the component in 2.1 only

@stof stof commented on the diff Apr 11, 2012
components/event_dispatcher/generic_event.rst
+ }
+
+Passing and processing arguments::
+
+ use Symfony\Component\EventDispatcher\GenericEvent;
+
+ $event = GenericEvent($subject, array('type' => 'foo', 'counter' => 0)));
+ $dispatcher->dispatch('foo', $event);
+
+ echo $event['counter'];
+
+ class FooListener
+ {
+ public function handler(GenericEvent $event)
+ {
+ if (isset($event['type']) && $event['type'] == 'foo') {
@stof
stof Apr 11, 2012

=== would be better :)

@stof stof commented on the diff Apr 11, 2012
components/http_foundation/http_foundation.rst
+Based on such a request, you can override the PHP global variables via
+:method:`Symfony\\Component\\HttpFoundation\\Request::overrideGlobals`::
+
+ $request->overrideGlobals();
+
+.. tip::
+
+ You can also duplicate an existing query via
+ :method:`Symfony\\Component\\HttpFoundation\\Request::duplicate` or
+ change a bunch of parameters with a single call to
+ :method:`Symfony\\Component\\HttpFoundation\\Request::initialize`.
+
+Accessing the Session
+~~~~~~~~~~~~~~~~~~~~~
+
+If you have a session attached to the Request, you can access it via the
@stof
stof Apr 11, 2012

you should link to the page talking about the session

@stof stof commented on the diff Apr 11, 2012
components/http_foundation/http_foundation.rst
+attribute::
+
+ use Symfony\Component\HttpFoundation\Cookie;
+
+ $response->headers->setCookie(new Cookie('foo', 'bar'));
+
+The
+:method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::setCookie`
+method takes an instance of
+:class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument.
+
+You can clear a cookie via the
+:method:`Symfony\\Component\\HttpFoundation\\Response::clearCookie` method.
+
+Managing the HTTP Cache
+~~~~~~~~~~~~~~~~~~~~~~~
@stof
stof Apr 11, 2012

there is already a page about the HTTP cache in the book so you should avoid duplicating things in the component. IMO it should be moved to the component doc but it should probably be a separate page, and the current doc is far more complete

@ghost
ghost Apr 12, 2012

This was already part of the document, maybe it can be moved in a separate PR. Once this PR has been merged it will be a lot easier to split up documents into precise chapters. I think it is very important that the component documentation is complete and that there is no confusion between the 'book' and the component docs, since the book refers to Symfony2 in the context of Symfony2 framework and so could be confusing. Anyhow, I'll take care of it in a separate PR.

@stof
Symfony member

You should split these changes into several commits because most changes are relevant for the 2.0 branch (components exist there too) but some new files should only be added in master (GenericEvent for instance)

@ghost

Closing this PR to do splits in 2.0

@ghost ghost closed this Apr 12, 2012
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment