Part deux, the design doc. What I still miss after reading this: - what is the purpose of filters? - what functionality will actually be provided in the default implementation? - proposed program flow? How do you handle merging of several result objects?
Cheers, Frederik > eZ component: MvcTools, Design > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > :Revision: $Rev$ > :Date: $Date$ > :Status: Draft > > .. contents:: > > Scope > ===== > > The scope of this document is to describe the initial design of a component > that provides classes to implement a MVC_ architecture for a web > application. > > .. _MVC: http://en.wikipedia.org/wiki/Model-view-controller > > Design overview > =============== > > Because of the variety of protocols and formats that a modern PHP > application should handle, this MVC implementation will provide an > abstraction for input and output of controllers. Besides that, a few tieins > will be provided. > > Some of the classes of this component are ezcMvcRequest and ezcMvcResult, > which represent the abstract request object for a controller and the > abstract result object that the controller returns. > > Beside these abstraction classes a collection of interfaces and classes > will be provided for routing, request-parsing, view-managing and > view-handling. This will allow the user of this component to build his own > MVC_ on basis of the components building blocks and to adjust it to his > needs. > > Very basic implementations of these interfaces will be shipped with the > component, that can be used for very basic applications and are mainly > meant as reference implementations. In future tie-ins with other eZ > Components might be provided, that ship with more advanced implementations. > > Layers > ====== > > The component is divided into 4 layers: > > The request parsing layer is represented by the ezcMvcRequestParser > interface. An instance of a implementing this interface is responsible for > parsing an incoming request and creating an instance of ezcMvcRequest from > it. This object will encapsulate the complete request data, independent > from the protocol and format used for the request. It will also contain raw > protocol data. > > The routing layer, represented by the ezcMvcRouter interface, is in charge > of selecting the correct controller to handle the request, based on the > ezcMvcRequest object it received. > > Controllers represent the third layer. At this level: Classes process the > request, based on the ezcMvcRequest object they received, and select the > data to be used to create a response. Controllers only accept an instance > of ezcMvcRequest as input and are responsible for returning an instance of > ezcMvcResult, encapsulating all data necessary to render the response. > > View management is the final layer, which is based on the incoming > ezcMvcRequest object and the ezcMvcResult object created by the > controllers. An instance of a class implementing the ezcMvcViewManager > interface uses one or more instances of ezcMvcViewHandler to create the > actual response and to send it to the client. > > Classes > ======= > > ezcMvcRequestFilter > ------------------- > > Provides an interface for request filters. Request filters can be used to > modify the request data before it is used by the controller. They are run > in the runRequestFilters() method of the ezcMvcController interface:: > > public function filterRequest( ezcMvcRequest $request ); If you use a second controller does it use the filtered data or the original one? Will the second controller have filters as well? > ezcMvcResultFilter > ------------------ > > Provides an interface for result filters. Filters that implement this > interface can be run after a controller have run their action. They are run > in the runResultFilters() method of the ezcMvcController interface:: > > public function filterResult( ezcMvcResult $result ); > > ezcMvcResponseFilter > -------------------- > > Provides an interface for response filters. Response filters are run after > the view handlers have created a response from the result. This can modify > the final output stream and headers. They are run in the runFilters method > of the ezcMvcViewHandler interface:: > > public function filterResponse( ezcMvcResponse $response ); > > > ezcMvcResponse > -------------- > > A struct that encapsulates the body and headers that form a response:: > > public $body = null; > public $headers = array(); > > ezcMvcRequestParser > ------------------- > > The ezcMvcRequestParser interface has to be implemented by classes that > will parse a request and create an ezcMvcInput object. No mention of ezcMvcInput anywhere else. What is it? > Methods:: > > /** > * Create the request object and then run the filters > * on it. The filters should be instanciate in runFilters(), > * which should be implemented by the user. > * > * @return ezcMvcRequest > */ > public function createRequest(); > public function runFilters( ezcMvcRequest $request ) > { > // empty, user can overload > } > > ezcMvcRequest > ------------- > > An instance of this class encapsulates a client-request, abstracting from > the request protocol and format. > > To separate the class properties of the input object, containing settings > and the object state, from the request data it carries, the class will > provide an array-like $data property that is exclusively reserved for > request data. It is very unclear to me what an instance of ezcMvcRequest will look like. Could you give a few examples here? Who is it that controls the structure of this? Is it enforced by mvctools or is this entirely up to the developer (or is that a choice?) There is no interface definition here so I can only guess that it is entirely application specific. If so, you need strong guidelines to what you should do here or people will create weird stuff :) The name ezcMvcRequestParser is confusing btw. To me it sounds like it should have ezcRequest objects as input not output. What about naming it ezcRequestBuilder? > ezcMvcResult > ------------ > > This object encapsulates the result of a controller, abstracting from the > actual response protocol. The output object will be modeled similar to the > input variant, described above. Needs examples as well. Same comments as for the request. > ezcMvcRouter > ------------ > > A class implementing this interface is in charge of using an instance of > ezcMvcRequest to select one or more controllers to run them and collect > their output (in form of ezcMvcResult objects). > > Methods:: > > /** > * Returns the controller for this request. > * > * @return ezcMvcController > */ > public function createController( ezcMvcRequest $input ) > > ezcMvcViewManager > ----------------- > > This interface has to be implemented by classes that are in charge of > coordinating the rendering of ezcMvcResult instances into a format > acceptable for the response protocol. The rendering itself is done by > instances of ezcViewHandler. > > Methods:: > > // want the view manager to use my filters > $viewHandler = $viewManager->createViewHandler( ezcMvcRequest $request, > ezcMvcResult $result ); > > ezcMvcViewHandler > ----------------- > > This abstract class has to be inherited by classes that handle rendering > one ezcMvcResult object into one specific format, that will be part of the > response. An instance of ezcMvcViewManager is responsible to coordinate > different view handlers and to merge their output to a consistent response. How does the view manager do that? The above view manager interface doesn't have any methods to provide this functionality? > Methods:: > > public function __construct( ezcMvcRequest $request, ezcMvcResult > $result ) > > /** > * Creates the response struct. > * > * @return ezcMvcResponse > */ > public function createResponse(); This is where the actual page rendering takes place right? > /** > * Sets the headers, outputs the body. > * > * @param ezcMvcResponse $response > * @return void > */ > public function handleResponse( ezcMvcResponse $response ); Handle doesn't really tell me that it is actually writing any output. Why not outputResponse() or writeResponse()? > > public function runFilters( ezcMvcResponse $response ) > { > // empty, user can overload > } > > /** > * Shortcut, see @uses > * > * @uses createResponse() > * @uses handleResponse() > * @return void > */ > public function handle(); What does this method do? -- Components mailing list [email protected] http://lists.ez.no/mailman/listinfo/components
