Hello everybody !
We are done with a final draft, document attached.
I'll post an implementation document first draft tomorrow morning.
I also want to thank two very special and talented persons whom
have higly contributed : Kore Nordmann and Tobias Schlitt.
This document would have never met such a high-quality (to my opinion)
without the experience and time that you have shared !
Cheers, James.
--
James Pic
eZ Component: MvcTools, Requirements
:Author: James Pic, Tobias Schlitt
:Revision: $Revision$
:Date: $Date$
Target and scope
The scope of this document is to describe the requirements for a component
providing classes to implement a MVC_ architecture for a web application. This
document does not describe the design of the named component, but only
summarizes the requirements for it as discussed on the developer mailinglist.
Where suitable, design related topics will be touched, but a dedicated design
document will follow later, defining APIs, classes and the architectural
structure of the component.
Note that if you don't understand a term, you should have a look at the section
`Clarification of terms`_.
Introduction
Model-View-Controller (MVC) is a common architecture pattern to implement all
kinds of applications using the object-oriented design paradigm. The goal of
the MvcTools component is to give users a basis for such architectures for web
applications written in PHP 5. The component shall not provide a full-featured
implementation of the MVC architecture, but should help users to easily create
their own, custom implementation.
A good starting point to learn more about MVC is the Wikipedia article:
http://en.wikipedia.org/wiki/Model-view-controller
Component integration
=
eZ Components already provide some components that are useful when
implementing an MVC. However, one basic goal of eZ Components is to keep
each component as independent as possible and to realize dependencies
through so-called tie-in components. Therefore the mechanisms realized in an
MVC component
should be that far abstracted, that other components can be tied in and
provide only very basic implementations on its own. This also allows
users to implement their own mechanisms. The following components have been
identified as possible tie-ins:
- Template_ (view)
- UserInput_ (routing)
- Url_ (routing)
- PersistentObject_ (models)
- EventLog_ (error-handling)
- Mail_ (error-handling, view)
.. _UserInput: http://ezcomponents.org/docs/tutorials/UserInput
.. _Url: http://ezcomponents.org/docs/tutorials/Url
.. _PersistentObject: http://ezcomponents.org/docs/tutorials/PersistentObject
.. _EventLog: http://ezcomponents.org/docs/tutorials/EventLog
.. _Mail: http://ezcomponents.org/docs/tutorials/Mail
For each of these components a tie-in component could considered to be
implemented at a later stage. This should be kept in mind when desigining the
classes/interfaces for the MvcTools component.
Design requirements
===
This section summarizes the requirements regarding the later following design
document.
I/O abstraction
Modern applications often require to deal with different input and output
protocols and formats (for example HTTP-GET, HTTP-POST, SOAP for the input part
and HTML, PDF, ReST-webservices for the output part). Therefore, protocols
input and output formats should be abstracted into dedicated objects, which are
not specific to a certain protocoll or format.
Controllers will only receive these abstracted data objects without knowledge
of the used format/protocol, to allow the re-use of 1 controller with severl
different input/output sources.
A benefic side-effect relates to controller-testing: Creating input and output
mocks and fixtures allows straight-forward TDD.
Summary
^^^
- Controllers should not know about the input and output environment but work
on abstract objects only.
Layers
--
The MvcTools component should distinguish certain layers to allow users to
easily adjust and replace certain functionality. Therefore, the following
requirements have been specified.
Controllers process and respond to events, typically user actions, and
may invoke changes on the model. In our case, controllers run an action using a
single argument: An input-object. A controller returns an output-object, after
being run.
Another different layer is responsible to select the controller to run and the
action to call on it. To create the input-object it requires the so-called
input-router. After the controller has been run, the output object is send to
the view-manager, which is responsible to select the correct rendering mode for
the output protocol/format.
Those two layers should be able to use any number of controllers per-request.
They handle the client-protocol, so that the controller doesn't have work on
raw input data (e.g. GET/POST/...) and does not have to generate any specific
