You are viewing a plain text version of this content. The canonical link for it is here.
Posted to zeta-commits@incubator.apache.org by je...@apache.org on 2011/08/05 07:22:46 UTC
[zeta-commits] svn commit: r1154102 [2/2] - in /incubator/zetacomponents: trunk/Mail/docs/
trunk/MvcTools/docs/ website/htdocs/documentation/trunk/
website/htdocs/documentation/trunk/Mail/
website/htdocs/documentation/trunk/MvcTools/
Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools.html?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools.html Fri Aug 5 07:22:45 2011
@@ -10,15 +10,15 @@
<meta name="description" content="Apache Zeta Components - reusable set of high quality PHP components to fasten your development." />
<meta name="keywords" content="PHP, apache, components, framework, quality" />
- <meta name="author" content="dotxp" />
+ <meta name="author" content="jerome" />
<meta name="language" content="en" />
- <meta name="date" content="Sat, 06 Nov 2010 12:08:09 +0100" />
+ <meta name="date" content="Fri, 05 Aug 2011 09:14:16 +0200" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="MvcTools" />
- <meta name="DC.creator" content="dotxp" />
- <meta name="DC.date" content="Sat, 06 Nov 2010 12:08:09 +0100" />
+ <meta name="DC.creator" content="jerome" />
+ <meta name="DC.date" content="Fri, 05 Aug 2011 09:14:16 +0200" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/documentation/trunk/MvcTools/tutorial.rdf" />
@@ -77,7 +77,7 @@
</ul>
- <h2>eZ Components - MvcTools</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#class-overview">Class Overview</a></p><ul><li><p><a href="#request-parsers">Request Parsers</a></p></li><li><p><a href="#router">Router</a></p></li><li><p><a href="#controller">Controller</a></p></li><li><p><a href="#view-handlers">View Handlers</a></p></li><li><p><a href="#response-writer">Response Writer</a></p></li><li><p><a href="#id2">Dispatchers</a></p></li></ul></li><li><p><a href="#a-simple-application-hello-world">A Simple Application: Hello World</a></p><ul><li><p><a href="#set-up">Set-up</a></p></li><li><p><a href="#dispatcher-configuration">Dispatcher Configuration</a></p></li><li><p><a href="#creating-the-router">Creating The Router</a></p></li><li><p><a href="#creating-the-controller">Creating the Controller</a></p></li><li><p><a href="#creating-the-views">Creating the Views</a></p></li><li><p><a href="#wrappi
ng-it-up">Wrapping it Up</a></p></li></ul></li></ul></li></ul></div><a name="introduction"></a><a name="id4"></a><h3>Introduction</h3><p>The MvcTools component provides an application developer with all the tools to architect his application framework. It is not meant to provide a full framework but merely provides the different parts that can be used. In this tutorial we'll use MvcTools to build <strong>HelloMvc</strong>, a classic application that greets the visitor in the choosen language. Its sources are available in the SVN at: <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc</a></p><p><strong>TheWire</strong> is a <a href="http://twitter.com">twitter</a> like application to share information which is architectured with MvcTools and avalaible in SVN as well, at <a href="https://svn.apache.org/repos/asf/incubator/zetacompone
nts/docs/examples/applications/TheWire/">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/</a>.</p><a name="class-overview"></a><a name="id5"></a><h4>Class Overview</h4><p>The MvcTools component provides classes dealing with the different parts of an MVC framework. It provides functionality for dispatching, routing, views generation, input parsing, output generation and filters. The diagram below shows the code flow through all the different parts.</p><div class=" 					image 					 							center 						 "><img alt="Request flow" title="Request flow" src="img/dispatcher-flow.png"/><span class="image_title">Request flow</span></div><p>The next few sections describe the different parts of the diagram. How this all ties together follows in the section .</p><a name="request-parsers"></a><a name="id6"></a><h5>Request Parsers</h5><p>The request parser is r
esponsible for taking input from a specific source and creating an abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object from this input data.</p><dl><dt>ezcMvcHttpRequestParser</dt><dd>Uses HTTP input to create a request object. This is the request parser you would use in most cases, as it's meant for the Web part of applications.</dd><dt>ezcMvcMailRequestParser</dt><dd>Uses an e-mail message to create a request object from. The request parser requires an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMail.html'>ezcMail</a> object and therefore this request parser is only available through the MvcMailTiein component.</dd></dl><a name="router"></a><a name="id7"></a><h5>Router</h5><p>The router analyses the request data in the abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object and decides which controller should be used to handle the in
coming request data. The router uses route objects to matched against request data. Those route objects do the matching themselves, and there are multiple implementations available. Each route is linked to a controller class, an action name and an optional set of extra variables that are either set in the route object instantiation, or defined by URL parameters.</p><dl><dt>ezcMvcRouter</dt><dd>Is an abstract class that should be inherited in the application to define the routes with the help of route objects of the classes <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> and <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a>. Matches are done against the full URI part of the request information.</dd><dt>ezcMvcRailsRoute</dt><dd>A route that uses a rails-like URL matcher to match against the URI. The pattern accepts parameters in URL elements starting with : (a colo
n). An example of a pattern is <code class="inline">/rss/tag/:tagName</code> where <code class="inline">:tagname</code> denotes a variable URL element with the name <em>tagName</em>.</dd><dt>ezcMvcRegexpRoute</dt><dd>This route class uses regular expressions to match URLs. Variables are defined by using named sub patterns. An example of a pattern is <code class="inline">@^people/(?P<name>.*)$@</code> â where <code class="inline">(?P<name>.*)</code> defines the location of a variable URL element with the name <em>name</em>. The <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a> patterns are more complex than <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> patterns, but also more powerful because you can name one URL position different depending on the contents such as in <code class="inline">@^people(/((?P<nr>[0-9]+)|(?P<name>.+)))?$@</
code> (the variable <em>nr</em> is returned if a sequence of numbers is matched, otherwise the variable <em>name</em> is returned.</dd></dl><a name="controller"></a><a name="id8"></a><h5>Controller</h5><p>The controller is created in the dispatcher by using information that is returned from the router (in the form of an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRoutingInformation.html'>ezcMvcRoutingInformation</a> object). It is up to the dispatcher on how the controller is created.</p><dl><dt>ezcMvcController</dt><dd>Every controller should inherit from this abstract class, which implements a constructor that sets the action method and creates object variables for each of the request variables. The abstract class also implements the createResult() method that will be called by the dispatcher to run an action. The implementations of the actions should be done in the inherited class.</dd></dl><a name="view-handlers"></a><a name="id9"></a><h5>View Hand
lers</h5><p>Each action returns an abstract object of the class <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcResult.html'>ezcMvcResult</a>. This object contains a set of variables that have to be rendered by a view. A view is selected by the dispatcher and controls the rendering of different sections (zones).</p><dl><dt>ezcMvcView</dt><dd>Is the abstract class that views should inherit from. Every view class should implement the createZones() method to configure the different zone of a view. Each zone can have a different view handler. And each view handler implements <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcViewHandler.html'>ezcMvcViewHandler</a> interface.</dd><dt>ezcMvcPhpViewHandler</dt><dd>This view handler uses a plain PHP script to process the result variables. All result variables are available as properties on the $this object.</dd><dt>ezcMvcJsonViewHandler</dt><dd>The JSON view handler collects all the variables, and
the result from previous zones into an array that is then encoded as JSON.</dd><dt>ezcMvcTemplateViewHandler</dt><dd>This view handler uses the Template component for rendering result variables. It is part of the MvcTemplateTiein package. Variables are simply passed as template variables.</dd></dl><a name="response-writer"></a><a name="id10"></a><h5>Response Writer</h5><p>The response writers are responsible for outputting the rendered result.</p><dl><dt>ezcMvcHttpResponseWriter</dt><dd>Uses HTTP to output the rendered result. This is what you would normally use for web applications. The response writer will also set the correct headers.</dd></dl><a name="id2"></a><a name="id11"></a><h5>Dispatchers</h5><p>The dispatcher is responsible for the whole flow of a request. Dispatchers should implement the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcher.html'>ezcMvcDispatcher</a> interface. The component comes with only one basic dispatcher at the mome
nt.</p><dl><dt>ezcMvcConfigurableDispatcher</dt><dd>The configurable dispatcher takes as parameter an object of a class that implements the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface. The dispatcher uses information from this object to decide on any of the above mentioned categories.</dd><dt>ezcMvcDispatcherConfiguration</dt><dd>This interface describes the methods for creating the request parser, router, views and response writers. Besides the above mentioned elements it also is responsible for creating the correct request object for fatal errors and the selection and running of filters. Where the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcConfigurableDispatcher.html'>ezcMvcConfigurableDispatcher</a> object is responsible for running the code, a class implementing the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfigurat
ion.html'>ezcMvcDispatcherConfiguration</a> interface is responsible for selecting and configuring the application's specifics.</dd></dl><a name="a-simple-application-hello-world"></a><a name="id12"></a><h4>A Simple Application: Hello World</h4><p>Before we go all the way with a complex application such as TheWire we'll be implementing a very simple application with only a few routes, one controller and two views. From this simple base we will then continue later on with adding more complex elements and end up with TheWire.</p><a name="set-up"></a><a name="id13"></a><h5>Set-up</h5><p>First of all, we need to create a directory structure. Because we do not want all of our code available directly through the web server will will place the libraries and other related files outside of the document root. We therefore create four directories under our application root: cache, lib, templates and www.</p><p>In the top level directory (HelloMvc) we place a config.php file, where we s
et the include path, add the class repository and configure the Template component. The file is otherwise really simple:</p><ol class="code">
+ <h2>eZ Components - MvcTools</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#class-overview">Class Overview</a></p><ul><li><p><a href="#request-parsers">Request Parsers</a></p></li><li><p><a href="#router">Router</a></p></li><li><p><a href="#controller">Controller</a></p></li><li><p><a href="#view-handlers">View Handlers</a></p></li><li><p><a href="#response-writer">Response Writer</a></p></li><li><p><a href="#id2">Dispatchers</a></p></li></ul></li><li><p><a href="#a-simple-application-hello-world">A Simple Application: Hello World</a></p><ul><li><p><a href="#set-up">Set-up</a></p></li><li><p><a href="#dispatcher-configuration">Dispatcher Configuration</a></p></li><li><p><a href="#creating-the-router">Creating The Router</a></p></li><li><p><a href="#creating-the-controller">Creating the Controller</a></p></li><li><p><a href="#creating-the-views">Creating the Views</a></p></li><li><p><a href="#wrappi
ng-it-up">Wrapping it Up</a></p></li></ul></li></ul></li><li><p><a href="#security">Security</a></p><ul><li><p><a href="#overriding-the-x-powered-by-header">Overriding the X-Powered-By header</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id4"></a><h3>Introduction</h3><p>The MvcTools component provides an application developer with all the tools to architect his application framework. It is not meant to provide a full framework but merely provides the different parts that can be used. In this tutorial we'll use MvcTools to build <strong>HelloMvc</strong>, a classic application that greets the visitor in the choosen language. Its sources are available in the SVN at: <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc</a></p><p><strong>TheWire</strong> is a <a href="http://twitter.com">twitter</a> like applicati
on to share information which is architectured with MvcTools and avalaible in SVN as well, at <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/</a>.</p><a name="class-overview"></a><a name="id5"></a><h4>Class Overview</h4><p>The MvcTools component provides classes dealing with the different parts of an MVC framework. It provides functionality for dispatching, routing, views generation, input parsing, output generation and filters. The diagram below shows the code flow through all the different parts.</p><div class=" 					image 					 							center 						 "><img alt="Request flow" title="Request flow" src="img/dispatcher-flow.png"/><span class="image_title">Request flow</span></div><p>The next few sections describe the different parts of the diagr
am. How this all ties together follows in the section .</p><a name="request-parsers"></a><a name="id6"></a><h5>Request Parsers</h5><p>The request parser is responsible for taking input from a specific source and creating an abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object from this input data.</p><dl><dt>ezcMvcHttpRequestParser</dt><dd>Uses HTTP input to create a request object. This is the request parser you would use in most cases, as it's meant for the Web part of applications.</dd><dt>ezcMvcMailRequestParser</dt><dd>Uses an e-mail message to create a request object from. The request parser requires an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMail.html'>ezcMail</a> object and therefore this request parser is only available through the MvcMailTiein component.</dd></dl><a name="router"></a><a name="id7"></a><h5>Router</h5><p>The router analyses the request data in the abstract <a href='
/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object and decides which controller should be used to handle the incoming request data. The router uses route objects to matched against request data. Those route objects do the matching themselves, and there are multiple implementations available. Each route is linked to a controller class, an action name and an optional set of extra variables that are either set in the route object instantiation, or defined by URL parameters.</p><dl><dt>ezcMvcRouter</dt><dd>Is an abstract class that should be inherited in the application to define the routes with the help of route objects of the classes <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> and <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a>. Matches are done against the full URI part of the request information.</dd><dt>ezcMvcR
ailsRoute</dt><dd>A route that uses a rails-like URL matcher to match against the URI. The pattern accepts parameters in URL elements starting with : (a colon). An example of a pattern is <code class="inline">/rss/tag/:tagName</code> where <code class="inline">:tagname</code> denotes a variable URL element with the name <em>tagName</em>.</dd><dt>ezcMvcRegexpRoute</dt><dd>This route class uses regular expressions to match URLs. Variables are defined by using named sub patterns. An example of a pattern is <code class="inline">@^people/(?P<name>.*)$@</code> â where <code class="inline">(?P<name>.*)</code> defines the location of a variable URL element with the name <em>name</em>. The <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a> patterns are more complex than <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> patterns, but also more powerful becaus
e you can name one URL position different depending on the contents such as in <code class="inline">@^people(/((?P<nr>[0-9]+)|(?P<name>.+)))?$@</code> (the variable <em>nr</em> is returned if a sequence of numbers is matched, otherwise the variable <em>name</em> is returned.</dd></dl><a name="controller"></a><a name="id8"></a><h5>Controller</h5><p>The controller is created in the dispatcher by using information that is returned from the router (in the form of an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRoutingInformation.html'>ezcMvcRoutingInformation</a> object). It is up to the dispatcher on how the controller is created.</p><dl><dt>ezcMvcController</dt><dd>Every controller should inherit from this abstract class, which implements a constructor that sets the action method and creates object variables for each of the request variables. The abstract class also implements the createResult() method that will be called by the dispatcher to
run an action. The implementations of the actions should be done in the inherited class.</dd></dl><a name="view-handlers"></a><a name="id9"></a><h5>View Handlers</h5><p>Each action returns an abstract object of the class <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcResult.html'>ezcMvcResult</a>. This object contains a set of variables that have to be rendered by a view. A view is selected by the dispatcher and controls the rendering of different sections (zones).</p><dl><dt>ezcMvcView</dt><dd>Is the abstract class that views should inherit from. Every view class should implement the createZones() method to configure the different zone of a view. Each zone can have a different view handler. And each view handler implements <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcViewHandler.html'>ezcMvcViewHandler</a> interface.</dd><dt>ezcMvcPhpViewHandler</dt><dd>This view handler uses a plain PHP script to process the result variables. All r
esult variables are available as properties on the $this object.</dd><dt>ezcMvcJsonViewHandler</dt><dd>The JSON view handler collects all the variables, and the result from previous zones into an array that is then encoded as JSON.</dd><dt>ezcMvcTemplateViewHandler</dt><dd>This view handler uses the Template component for rendering result variables. It is part of the MvcTemplateTiein package. Variables are simply passed as template variables.</dd></dl><a name="response-writer"></a><a name="id10"></a><h5>Response Writer</h5><p>The response writers are responsible for outputting the rendered result.</p><dl><dt>ezcMvcHttpResponseWriter</dt><dd>Uses HTTP to output the rendered result. This is what you would normally use for web applications. The response writer will also set the correct headers.</dd></dl><a name="id2"></a><a name="id11"></a><h5>Dispatchers</h5><p>The dispatcher is responsible for the whole flow of a request. Dispatchers should implement the <a href='/zetacompone
nts/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcher.html'>ezcMvcDispatcher</a> interface. The component comes with only one basic dispatcher at the moment.</p><dl><dt>ezcMvcConfigurableDispatcher</dt><dd>The configurable dispatcher takes as parameter an object of a class that implements the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface. The dispatcher uses information from this object to decide on any of the above mentioned categories.</dd><dt>ezcMvcDispatcherConfiguration</dt><dd>This interface describes the methods for creating the request parser, router, views and response writers. Besides the above mentioned elements it also is responsible for creating the correct request object for fatal errors and the selection and running of filters. Where the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcConfigurableDispatcher.html'>ezcMvcConfigurableDispatcher</a>
object is responsible for running the code, a class implementing the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface is responsible for selecting and configuring the application's specifics.</dd></dl><a name="a-simple-application-hello-world"></a><a name="id12"></a><h4>A Simple Application: Hello World</h4><p>Before we go all the way with a complex application such as TheWire we'll be implementing a very simple application with only a few routes, one controller and two views. From this simple base we will then continue later on with adding more complex elements and end up with TheWire.</p><a name="set-up"></a><a name="id13"></a><h5>Set-up</h5><p>First of all, we need to create a directory structure. Because we do not want all of our code available directly through the web server will will place the libraries and other related files outside of the document root. We therefore create f
our directories under our application root: cache, lib, templates and www.</p><p>In the top level directory (HelloMvc) we place a config.php file, where we set the include path, add the class repository and configure the Template component. The file is otherwise really simple:</p><ol class="code">
<li><span style="color: #000000"><?php</span></li>
<li><span style="color: #007700">// Set the include path to the eZ Components location, and bootstrap the</span></li>
<li><span style="color: #007700">// library. The two lines below assume that you're using eZ Components from</span></li>
@@ -294,7 +294,7 @@ RewriteRule ^.*$ index.php [NC,L]
âââ www/
â âââ .htaccess
â âââ index.php
-âââ config.php</code><!--Local Variables:
+âââ config.php</code><a name="security"></a><a name="id19"></a><h3>Security</h3><a name="overriding-the-x-powered-by-header"></a><a name="id20"></a><h4>Overriding the X-Powered-By header</h4><p>By default, the MvcTools component will add an X-Powered-By HTTP header containing the string "Apache Zeta Components MvcTools" or "eZ Components MvcTools". This can be considered a security issue. If you want to modify this header you can add the following code in your response filter:</p><code class="block">$response->generator = "Whatever you want here";</code><!--Local Variables:
mode: rst
fill-column: 79
End:
Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.html
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.html?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.html (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.html Fri Aug 5 07:22:45 2011
@@ -10,15 +10,15 @@
<meta name="description" content="Apache Zeta Components - reusable set of high quality PHP components to fasten your development." />
<meta name="keywords" content="PHP, apache, components, framework, quality" />
- <meta name="author" content="dotxp" />
+ <meta name="author" content="jerome" />
<meta name="language" content="en" />
- <meta name="date" content="Sat, 06 Nov 2010 12:08:09 +0100" />
+ <meta name="date" content="Fri, 05 Aug 2011 09:14:16 +0200" />
<meta name="robots" content="all" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.title" content="Tutorial" />
- <meta name="DC.creator" content="dotxp" />
- <meta name="DC.date" content="Sat, 06 Nov 2010 12:08:09 +0100" />
+ <meta name="DC.creator" content="jerome" />
+ <meta name="DC.date" content="Fri, 05 Aug 2011 09:14:16 +0200" />
<meta name="DC.rights" content="Copyright" />
<link rel="meta" href="/zetacomponents/documentation/trunk/MvcTools/tutorial.rdf" />
@@ -77,7 +77,7 @@
</ul>
- <h2>eZ Components - MvcTools</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#class-overview">Class Overview</a></p><ul><li><p><a href="#request-parsers">Request Parsers</a></p></li><li><p><a href="#router">Router</a></p></li><li><p><a href="#controller">Controller</a></p></li><li><p><a href="#view-handlers">View Handlers</a></p></li><li><p><a href="#response-writer">Response Writer</a></p></li><li><p><a href="#id2">Dispatchers</a></p></li></ul></li><li><p><a href="#a-simple-application-hello-world">A Simple Application: Hello World</a></p><ul><li><p><a href="#set-up">Set-up</a></p></li><li><p><a href="#dispatcher-configuration">Dispatcher Configuration</a></p></li><li><p><a href="#creating-the-router">Creating The Router</a></p></li><li><p><a href="#creating-the-controller">Creating the Controller</a></p></li><li><p><a href="#creating-the-views">Creating the Views</a></p></li><li><p><a href="#wrappi
ng-it-up">Wrapping it Up</a></p></li></ul></li></ul></li></ul></div><a name="introduction"></a><a name="id4"></a><h3>Introduction</h3><p>The MvcTools component provides an application developer with all the tools to architect his application framework. It is not meant to provide a full framework but merely provides the different parts that can be used. In this tutorial we'll use MvcTools to build <strong>HelloMvc</strong>, a classic application that greets the visitor in the choosen language. Its sources are available in the SVN at: <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc</a></p><p><strong>TheWire</strong> is a <a href="http://twitter.com">twitter</a> like application to share information which is architectured with MvcTools and avalaible in SVN as well, at <a href="https://svn.apache.org/repos/asf/incubator/zetacompone
nts/docs/examples/applications/TheWire/">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/</a>.</p><a name="class-overview"></a><a name="id5"></a><h4>Class Overview</h4><p>The MvcTools component provides classes dealing with the different parts of an MVC framework. It provides functionality for dispatching, routing, views generation, input parsing, output generation and filters. The diagram below shows the code flow through all the different parts.</p><div class=" 					image 					 							center 						 "><img alt="Request flow" title="Request flow" src="img/dispatcher-flow.png"/><span class="image_title">Request flow</span></div><p>The next few sections describe the different parts of the diagram. How this all ties together follows in the section .</p><a name="request-parsers"></a><a name="id6"></a><h5>Request Parsers</h5><p>The request parser is r
esponsible for taking input from a specific source and creating an abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object from this input data.</p><dl><dt>ezcMvcHttpRequestParser</dt><dd>Uses HTTP input to create a request object. This is the request parser you would use in most cases, as it's meant for the Web part of applications.</dd><dt>ezcMvcMailRequestParser</dt><dd>Uses an e-mail message to create a request object from. The request parser requires an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMail.html'>ezcMail</a> object and therefore this request parser is only available through the MvcMailTiein component.</dd></dl><a name="router"></a><a name="id7"></a><h5>Router</h5><p>The router analyses the request data in the abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object and decides which controller should be used to handle the in
coming request data. The router uses route objects to matched against request data. Those route objects do the matching themselves, and there are multiple implementations available. Each route is linked to a controller class, an action name and an optional set of extra variables that are either set in the route object instantiation, or defined by URL parameters.</p><dl><dt>ezcMvcRouter</dt><dd>Is an abstract class that should be inherited in the application to define the routes with the help of route objects of the classes <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> and <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a>. Matches are done against the full URI part of the request information.</dd><dt>ezcMvcRailsRoute</dt><dd>A route that uses a rails-like URL matcher to match against the URI. The pattern accepts parameters in URL elements starting with : (a colo
n). An example of a pattern is <code class="inline">/rss/tag/:tagName</code> where <code class="inline">:tagname</code> denotes a variable URL element with the name <em>tagName</em>.</dd><dt>ezcMvcRegexpRoute</dt><dd>This route class uses regular expressions to match URLs. Variables are defined by using named sub patterns. An example of a pattern is <code class="inline">@^people/(?P<name>.*)$@</code> â where <code class="inline">(?P<name>.*)</code> defines the location of a variable URL element with the name <em>name</em>. The <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a> patterns are more complex than <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> patterns, but also more powerful because you can name one URL position different depending on the contents such as in <code class="inline">@^people(/((?P<nr>[0-9]+)|(?P<name>.+)))?$@</
code> (the variable <em>nr</em> is returned if a sequence of numbers is matched, otherwise the variable <em>name</em> is returned.</dd></dl><a name="controller"></a><a name="id8"></a><h5>Controller</h5><p>The controller is created in the dispatcher by using information that is returned from the router (in the form of an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRoutingInformation.html'>ezcMvcRoutingInformation</a> object). It is up to the dispatcher on how the controller is created.</p><dl><dt>ezcMvcController</dt><dd>Every controller should inherit from this abstract class, which implements a constructor that sets the action method and creates object variables for each of the request variables. The abstract class also implements the createResult() method that will be called by the dispatcher to run an action. The implementations of the actions should be done in the inherited class.</dd></dl><a name="view-handlers"></a><a name="id9"></a><h5>View Hand
lers</h5><p>Each action returns an abstract object of the class <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcResult.html'>ezcMvcResult</a>. This object contains a set of variables that have to be rendered by a view. A view is selected by the dispatcher and controls the rendering of different sections (zones).</p><dl><dt>ezcMvcView</dt><dd>Is the abstract class that views should inherit from. Every view class should implement the createZones() method to configure the different zone of a view. Each zone can have a different view handler. And each view handler implements <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcViewHandler.html'>ezcMvcViewHandler</a> interface.</dd><dt>ezcMvcPhpViewHandler</dt><dd>This view handler uses a plain PHP script to process the result variables. All result variables are available as properties on the $this object.</dd><dt>ezcMvcJsonViewHandler</dt><dd>The JSON view handler collects all the variables, and
the result from previous zones into an array that is then encoded as JSON.</dd><dt>ezcMvcTemplateViewHandler</dt><dd>This view handler uses the Template component for rendering result variables. It is part of the MvcTemplateTiein package. Variables are simply passed as template variables.</dd></dl><a name="response-writer"></a><a name="id10"></a><h5>Response Writer</h5><p>The response writers are responsible for outputting the rendered result.</p><dl><dt>ezcMvcHttpResponseWriter</dt><dd>Uses HTTP to output the rendered result. This is what you would normally use for web applications. The response writer will also set the correct headers.</dd></dl><a name="id2"></a><a name="id11"></a><h5>Dispatchers</h5><p>The dispatcher is responsible for the whole flow of a request. Dispatchers should implement the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcher.html'>ezcMvcDispatcher</a> interface. The component comes with only one basic dispatcher at the mome
nt.</p><dl><dt>ezcMvcConfigurableDispatcher</dt><dd>The configurable dispatcher takes as parameter an object of a class that implements the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface. The dispatcher uses information from this object to decide on any of the above mentioned categories.</dd><dt>ezcMvcDispatcherConfiguration</dt><dd>This interface describes the methods for creating the request parser, router, views and response writers. Besides the above mentioned elements it also is responsible for creating the correct request object for fatal errors and the selection and running of filters. Where the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcConfigurableDispatcher.html'>ezcMvcConfigurableDispatcher</a> object is responsible for running the code, a class implementing the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfigurat
ion.html'>ezcMvcDispatcherConfiguration</a> interface is responsible for selecting and configuring the application's specifics.</dd></dl><a name="a-simple-application-hello-world"></a><a name="id12"></a><h4>A Simple Application: Hello World</h4><p>Before we go all the way with a complex application such as TheWire we'll be implementing a very simple application with only a few routes, one controller and two views. From this simple base we will then continue later on with adding more complex elements and end up with TheWire.</p><a name="set-up"></a><a name="id13"></a><h5>Set-up</h5><p>First of all, we need to create a directory structure. Because we do not want all of our code available directly through the web server will will place the libraries and other related files outside of the document root. We therefore create four directories under our application root: cache, lib, templates and www.</p><p>In the top level directory (HelloMvc) we place a config.php file, where we s
et the include path, add the class repository and configure the Template component. The file is otherwise really simple:</p><ol class="code">
+ <h2>eZ Components - MvcTools</h2><div class="toc"><h3>Table of Contents</h3><ul><li><p><a href="#introduction">Introduction</a></p><ul><li><p><a href="#class-overview">Class Overview</a></p><ul><li><p><a href="#request-parsers">Request Parsers</a></p></li><li><p><a href="#router">Router</a></p></li><li><p><a href="#controller">Controller</a></p></li><li><p><a href="#view-handlers">View Handlers</a></p></li><li><p><a href="#response-writer">Response Writer</a></p></li><li><p><a href="#id2">Dispatchers</a></p></li></ul></li><li><p><a href="#a-simple-application-hello-world">A Simple Application: Hello World</a></p><ul><li><p><a href="#set-up">Set-up</a></p></li><li><p><a href="#dispatcher-configuration">Dispatcher Configuration</a></p></li><li><p><a href="#creating-the-router">Creating The Router</a></p></li><li><p><a href="#creating-the-controller">Creating the Controller</a></p></li><li><p><a href="#creating-the-views">Creating the Views</a></p></li><li><p><a href="#wrappi
ng-it-up">Wrapping it Up</a></p></li></ul></li></ul></li><li><p><a href="#security">Security</a></p><ul><li><p><a href="#overriding-the-x-powered-by-header">Overriding the X-Powered-By header</a></p></li></ul></li></ul></div><a name="introduction"></a><a name="id4"></a><h3>Introduction</h3><p>The MvcTools component provides an application developer with all the tools to architect his application framework. It is not meant to provide a full framework but merely provides the different parts that can be used. In this tutorial we'll use MvcTools to build <strong>HelloMvc</strong>, a classic application that greets the visitor in the choosen language. Its sources are available in the SVN at: <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/HelloMvc</a></p><p><strong>TheWire</strong> is a <a href="http://twitter.com">twitter</a> like applicati
on to share information which is architectured with MvcTools and avalaible in SVN as well, at <a href="https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/">https://svn.apache.org/repos/asf/incubator/zetacomponents/docs/examples/applications/TheWire/</a>.</p><a name="class-overview"></a><a name="id5"></a><h4>Class Overview</h4><p>The MvcTools component provides classes dealing with the different parts of an MVC framework. It provides functionality for dispatching, routing, views generation, input parsing, output generation and filters. The diagram below shows the code flow through all the different parts.</p><div class=" 					image 					 							center 						 "><img alt="Request flow" title="Request flow" src="img/dispatcher-flow.png"/><span class="image_title">Request flow</span></div><p>The next few sections describe the different parts of the diagr
am. How this all ties together follows in the section .</p><a name="request-parsers"></a><a name="id6"></a><h5>Request Parsers</h5><p>The request parser is responsible for taking input from a specific source and creating an abstract <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object from this input data.</p><dl><dt>ezcMvcHttpRequestParser</dt><dd>Uses HTTP input to create a request object. This is the request parser you would use in most cases, as it's meant for the Web part of applications.</dd><dt>ezcMvcMailRequestParser</dt><dd>Uses an e-mail message to create a request object from. The request parser requires an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMail.html'>ezcMail</a> object and therefore this request parser is only available through the MvcMailTiein component.</dd></dl><a name="router"></a><a name="id7"></a><h5>Router</h5><p>The router analyses the request data in the abstract <a href='
/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRequest.html'>ezcMvcRequest</a> object and decides which controller should be used to handle the incoming request data. The router uses route objects to matched against request data. Those route objects do the matching themselves, and there are multiple implementations available. Each route is linked to a controller class, an action name and an optional set of extra variables that are either set in the route object instantiation, or defined by URL parameters.</p><dl><dt>ezcMvcRouter</dt><dd>Is an abstract class that should be inherited in the application to define the routes with the help of route objects of the classes <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> and <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a>. Matches are done against the full URI part of the request information.</dd><dt>ezcMvcR
ailsRoute</dt><dd>A route that uses a rails-like URL matcher to match against the URI. The pattern accepts parameters in URL elements starting with : (a colon). An example of a pattern is <code class="inline">/rss/tag/:tagName</code> where <code class="inline">:tagname</code> denotes a variable URL element with the name <em>tagName</em>.</dd><dt>ezcMvcRegexpRoute</dt><dd>This route class uses regular expressions to match URLs. Variables are defined by using named sub patterns. An example of a pattern is <code class="inline">@^people/(?P<name>.*)$@</code> â where <code class="inline">(?P<name>.*)</code> defines the location of a variable URL element with the name <em>name</em>. The <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRegexpRoute.html'>ezcMvcRegexpRoute</a> patterns are more complex than <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRailsRoute.html'>ezcMvcRailsRoute</a> patterns, but also more powerful becaus
e you can name one URL position different depending on the contents such as in <code class="inline">@^people(/((?P<nr>[0-9]+)|(?P<name>.+)))?$@</code> (the variable <em>nr</em> is returned if a sequence of numbers is matched, otherwise the variable <em>name</em> is returned.</dd></dl><a name="controller"></a><a name="id8"></a><h5>Controller</h5><p>The controller is created in the dispatcher by using information that is returned from the router (in the form of an <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcRoutingInformation.html'>ezcMvcRoutingInformation</a> object). It is up to the dispatcher on how the controller is created.</p><dl><dt>ezcMvcController</dt><dd>Every controller should inherit from this abstract class, which implements a constructor that sets the action method and creates object variables for each of the request variables. The abstract class also implements the createResult() method that will be called by the dispatcher to
run an action. The implementations of the actions should be done in the inherited class.</dd></dl><a name="view-handlers"></a><a name="id9"></a><h5>View Handlers</h5><p>Each action returns an abstract object of the class <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcResult.html'>ezcMvcResult</a>. This object contains a set of variables that have to be rendered by a view. A view is selected by the dispatcher and controls the rendering of different sections (zones).</p><dl><dt>ezcMvcView</dt><dd>Is the abstract class that views should inherit from. Every view class should implement the createZones() method to configure the different zone of a view. Each zone can have a different view handler. And each view handler implements <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcViewHandler.html'>ezcMvcViewHandler</a> interface.</dd><dt>ezcMvcPhpViewHandler</dt><dd>This view handler uses a plain PHP script to process the result variables. All r
esult variables are available as properties on the $this object.</dd><dt>ezcMvcJsonViewHandler</dt><dd>The JSON view handler collects all the variables, and the result from previous zones into an array that is then encoded as JSON.</dd><dt>ezcMvcTemplateViewHandler</dt><dd>This view handler uses the Template component for rendering result variables. It is part of the MvcTemplateTiein package. Variables are simply passed as template variables.</dd></dl><a name="response-writer"></a><a name="id10"></a><h5>Response Writer</h5><p>The response writers are responsible for outputting the rendered result.</p><dl><dt>ezcMvcHttpResponseWriter</dt><dd>Uses HTTP to output the rendered result. This is what you would normally use for web applications. The response writer will also set the correct headers.</dd></dl><a name="id2"></a><a name="id11"></a><h5>Dispatchers</h5><p>The dispatcher is responsible for the whole flow of a request. Dispatchers should implement the <a href='/zetacompone
nts/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcher.html'>ezcMvcDispatcher</a> interface. The component comes with only one basic dispatcher at the moment.</p><dl><dt>ezcMvcConfigurableDispatcher</dt><dd>The configurable dispatcher takes as parameter an object of a class that implements the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface. The dispatcher uses information from this object to decide on any of the above mentioned categories.</dd><dt>ezcMvcDispatcherConfiguration</dt><dd>This interface describes the methods for creating the request parser, router, views and response writers. Besides the above mentioned elements it also is responsible for creating the correct request object for fatal errors and the selection and running of filters. Where the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcConfigurableDispatcher.html'>ezcMvcConfigurableDispatcher</a>
object is responsible for running the code, a class implementing the <a href='/zetacomponents/documentation/trunk/MvcTools/phpdoc/ezcMvcDispatcherConfiguration.html'>ezcMvcDispatcherConfiguration</a> interface is responsible for selecting and configuring the application's specifics.</dd></dl><a name="a-simple-application-hello-world"></a><a name="id12"></a><h4>A Simple Application: Hello World</h4><p>Before we go all the way with a complex application such as TheWire we'll be implementing a very simple application with only a few routes, one controller and two views. From this simple base we will then continue later on with adding more complex elements and end up with TheWire.</p><a name="set-up"></a><a name="id13"></a><h5>Set-up</h5><p>First of all, we need to create a directory structure. Because we do not want all of our code available directly through the web server will will place the libraries and other related files outside of the document root. We therefore create f
our directories under our application root: cache, lib, templates and www.</p><p>In the top level directory (HelloMvc) we place a config.php file, where we set the include path, add the class repository and configure the Template component. The file is otherwise really simple:</p><ol class="code">
<li><span style="color: #000000"><?php</span></li>
<li><span style="color: #007700">// Set the include path to the eZ Components location, and bootstrap the</span></li>
<li><span style="color: #007700">// library. The two lines below assume that you're using eZ Components from</span></li>
@@ -294,7 +294,7 @@ RewriteRule ^.*$ index.php [NC,L]
âââ www/
â âââ .htaccess
â âââ index.php
-âââ config.php</code><!--Local Variables:
+âââ config.php</code><a name="security"></a><a name="id19"></a><h3>Security</h3><a name="overriding-the-x-powered-by-header"></a><a name="id20"></a><h4>Overriding the X-Powered-By header</h4><p>By default, the MvcTools component will add an X-Powered-By HTTP header containing the string "Apache Zeta Components MvcTools" or "eZ Components MvcTools". This can be considered a security issue. If you want to modify this header you can add the following code in your response filter:</p><code class="block">$response->generator = "Whatever you want here";</code><!--Local Variables:
mode: rst
fill-column: 79
End:
Modified: incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.txt?rev=1154102&r1=1154101&r2=1154102&view=diff
==============================================================================
--- incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.txt (original)
+++ incubator/zetacomponents/website/htdocs/documentation/trunk/MvcTools/tutorial.txt Fri Aug 5 07:22:45 2011
@@ -592,6 +592,18 @@ The full directory listing is now::
â âââ index.php
âââ config.php
+Security
+========
+
+Overriding the X-Powered-By header
+----------------------------------
+
+By default, the MvcTools component will add an `X-Powered-By` HTTP header
+containing the string "Apache Zeta Components MvcTools" or "eZ Components
+MvcTools". This can be considered a security issue. If you want to modify
+this header you can add the following code in your response filter: ::
+
+ $response->generator = "Whatever you want here";
..