TYPO3.Flow

<?xml version="1.0" encoding="UTF-8"?>

<chapter version="5.0" xml:id="flow3.mvcframework"

         xmlns="http://docbook.org/ns/docbook"

         xmlns:ns52="http://www.w3.org/1998/Math/MathML"

         xmlns:ns5="http://www.w3.org/1999/xlink"

         xmlns:ns4="http://www.w3.org/2000/svg"

         xmlns:ns3="http://www.w3.org/1999/xhtml"

         xmlns:ns="http://docbook.org/ns/docbook">

  <title>MVC Framework</title>

  <section xml:id="flow3.mvcframework.introduction">

    <title>Introduction</title>

    <section>

      <title>Model-View-Controller</title>

      <para>In the design of FLOW3's architecture we have taken great care to

      separate concerns and assign each part of the framework with

      well-defined tasks. The separation of concerns is an important principle

      of good software design and its most prominent representative probably

      is the Model-View-Controller pattern. MVC separates the business logic

      from the presentation by splitting up user interaction into three

      roles:</para>

      <itemizedlist>

        <listitem>

          <para>The <emphasis>model</emphasis> is an object which contains

          data and business logic of a certain domain. It doesn't contain any

          information about the presentation of that data, but rather defines

          the behaviour. In the FLOW3 project we prefer a special kind of

          model, the <link

          ns5:href="http://martinfowler.com/eaaCatalog/domainModel.html">Domain

          Model</link>.</para>

        </listitem>

        <listitem>

          <para>The <emphasis>view</emphasis> represents the display of the

          model on the web or another output channel. Views only display data,

          they don't build or modify it.</para>

        </listitem>

        <listitem>

          <para>The <emphasis>controller</emphasis> reacts on user input,

          selects and manipulates the model as accordingly, selects a view and

          passes it the prepared model for rendering.</para>

        </listitem>

      </itemizedlist>

      <para>This diagram outlines the collaboration between model, view and

      controller:</para>

      <figure>

        <title>Model-View-Controller Pattern</title>

        <mediaobject>

          <imageobject>

            <imagedata contentdepth="100%"

                       fileref="MVC_ModelViewController.png"

                       scalefit="1" width="100%"/>

          </imageobject>

        </mediaobject>

      </figure>

    </section>

    <section>

      <title>Other Patterns Used</title>

      <para>Design Patterns (and MVC is one of them) are not only great for

      solving reoccuring design problems in a structured manner - they also

      help you communicating software designs. The following patterns play an

      important role in FLOW3's MVC mechanism and might give you a better idea

      of the overall design:</para>

      <itemizedlist>

        <listitem>

          <para>Incoming requests are handled by a Request Handler which takes

          the role of a <link ns5:href="???">Front Controller</link>.</para>

        </listitem>

        <listitem>

          <para><link ns5:href="???">Template View</link> is the most commonly

          used pattern for views, but <link ns5:href="???">Transform

          Views</link> and <link ns5:href="???">Two-Step Views</link> are

          equally supported.</para>

        </listitem>

        <listitem>

          <para>The preferred type of model is the <link ns5:href="???">Domain

          Model</link>.</para>

        </listitem>

      </itemizedlist>

    </section>

    <section>

      <title>Hello World!</title>

      <para>Let's start with an example before we go into greater detail of

      request handling and the internals of the MVC framework. The minimal

      approach is to create an Action Controller which just returns

      <quote>Hello World!</quote>. To begin with, we need to create some

      directories which contain the code of our FLOW3 package and eventually

      the controller class:</para>

      <literallayout>Packages/

  Demo/

    Classes/

      Controller/

        StandardController.php</literallayout>

      <para>The StandardController class looks as simple as this (leaving out

      the very recommended comments):</para>

      <example>

        <title>Hello World! controller</title>

        <programlisting language="php">namespace TYPO3\Demo\Controller;

class StandardController extends \TYPO3\FLOW3\MVC\Controller\ActionController {

        public function indexAction() {

                return 'Hello World!';

        }

}</programlisting>

      </example>

      <para>Provided that the document root of your local server points to

      FLOW3's <filename>Web/</filename> directory, you will get the following

      output when calling the URI <uri>http://localhost/demo/</uri>:</para>

      <screen>Hello World!</screen>

      <para>Great, that was easy - but didn't we say that it's the view's

      responsibility to take care of the presentation? Let's create a simple

      PHP-based view for that purpose:</para>

      <literallayout>Packages/

  Demo/

    Classes/

      Controller/

        StandardController.php

      View/

        Standard/

          Index.php</literallayout>

      <para>The view's code is equally trivial:</para>

      <example>

        <title>Hello World! view</title>

        <programlisting language="php">namespace TYPO3\Demo\View\Standard;

class Index extends \TYPO3\FLOW3\MVC\View\AbstractView {

        public function render() {

                return 'Hello World from your view!';

        }

}</programlisting>

      </example>

      <para>Finally our action controller needs a little tweak to return the

      rendered view instead of shouting <quote>Hello World!</quote>

      itself:</para>

      <example>

        <title>Improved Hello World! controller</title>

        <programlisting language="php">namespace TYPO3\Demo\Controller;

class StandardController extends \TYPO3\FLOW3\MVC\Controller\ActionController {

        public function indexAction() {

                return $this->view->render();

        }

}</programlisting>

      </example>

      <para>Some notes about the view: Although a view class written in PHP is

      the most basic way to implement a view, it is not the most common way

      you'll take. In practice you'll want to use <package>Fluid</package>,

      FLOW3's powerful templating engine which allows you to write views in

      plain HTML and still have all the power like loops and

      conditions.</para>

    </section>

    <section>

      <title>Recommended File Structure</title>

      <para>As you have seen in the hello world example, conventions for the

      directory layout simplify your development a lot. There's no need to

      register controllers, actions or views if you follow our recommended

      file structure. These are the rules:</para>

      <itemizedlist>

        <listitem>

          <para><emphasis>Controllers</emphasis> are located in their own

          directory <filename>Controller</filename> just below the

          <filename>Classes</filename> directory of your package. They can

          have arbitrary names while the

          <classname>StandardController</classname> has a special meaning: If

          the package was specified in the request but no controller, the

          <classname>StandardController</classname> will be used.</para>

        </listitem>

        <listitem>

          <para><emphasis>View</emphasis> classes are situated below a

          <filename>View</filename> directory. The classname of the view is a

          combination of the name of the controller and the name of the

          action.</para>

        </listitem>

      </itemizedlist>

      <para>This sample directory layout demonstrates the above rules:</para>

      <example>

        <title>Sample file structure</title>

        <literallayout>Packages/

  Demo/

    Classes/

      Controller/

        StandardController.php

        CustomerController.php

        OrderController.php

      View/

        Standard/

          Index.php

        Customer/

          Index.php

          List.php

          Details.php

        Order/

          List.php</literallayout>

      </example>

      <para>Adhering to these conventions has the advantage that the classname

      of the view for example is resolved automatically. However it is

      possible (and not really difficult) to deviate from this layout and have

      a completely different structure.</para>

    </section>

    <section>

      <title>From the URI to the view</title>

      <caution>

        <para>For the example URIs we assume that the web root directory of

        your local server points to FLOW3's <filename>public/</filename>

        directory. If that's not the case you have to extend the URI

        accordingly.</para>

      </caution>

      <para>FLOW3 provides a standard way of resolving the URI to your

      MVC-Objects.</para>

      <para>Say, you want to see the list of customers (based on the

      file-structure-example above). The URI to get the list would be:

      <uri>http://localhost/demo/customer/list.html</uri> or just

      <uri>http://localhost/demo/customer/list</uri>.</para>

      <para>This URI will be resolved into the package-name

      (<emphasis>Demo</emphasis>), controller-name

      (<emphasis>Customer</emphasis>), action-name(<emphasis>list</emphasis>)

      and format-name (<emphasis>html</emphasis> - which is the default

      format).</para>

      <para>Depending on that, the controller

      <classname>\TYPO3\Demo\Controller\CustomerController</classname> (pattern:

      '<code>TYPO3\@package\Controller\@controllerController'</code>) and its

      method <methodname>listAction()</methodname> will be used. The

      corresponding view is <classname>\TYPO3\Demo\View\CustomerList</classname>

      (Pattern:

      <code>'TYPO3\@package\View\@controller@action@format'</code>).</para>

      <para>By looking at the view pattern you easily see that it's fairly

      easily to address a view which renders a different format, for example

      XML. All you need to do is creating a class called

      <classname>\TYPO3\Demo\View\Customer\ListXML</classname>. To see the output

      of this new view, just use the URI

      <uri>http://localhost/demo/customer/list.xml</uri>.</para>

    </section>

  </section>

  <section xml:id="flow3.mvcframework.requestresponse">

    <title>Request and Response</title>

    <para>No matter if a FLOW3 application runs in a web context or is

    launched from the command line, the basic workflow is always the same: The

    user request is analyzed and forwarded to an appropriate controller which

    decides on which actions to take and finally returns a response which is

    handed over to the user. This section highlights the flow and the

    collaborators in the request-response machinery.</para>

    <section>

      <title>Request Processing Overview</title>

      <para>A sequence diagram is worth a thousand words said my grandma, so

      let's take a look at the standard request-response workflow in

      FLOW3:</para>

      <figure>

        <title>Example of a Web Request-Response Workflow</title>

        <mediaobject>

          <imageobject>

            <imagedata contentdepth="100%"

                       fileref="MVC_RequestResponseWorkflow.png"

                       scalefit="1" width="100%"/>

          </imageobject>

        </mediaobject>

      </figure>

      <para>As you see, there are a lot of parts of the framework involved for

      answering a request - and the diagram doesn't even consider caching or

      forwarding of requests. But we didn't create this structure just for the

      fun of it - each object plays an important role as you'll see in the

      next sections.</para>

    </section>

    <section>

      <title>Request Handler</title>

      <para>The request handler takes the important task to handle and respond

      to a request. There exists exactly one request handler for each request

      type. By default web and command line requests are supported, but more

      specialized request handlers can be developed, too.</para>

      <para>Before one of the request handlers comes to play, the framework

      needs to determine which of them is the most suitable for the current

      request. The request handler resolver asks all of the registered request

      handlers to rate on a scale how well they can handle the current raw

      request. The resolver then chooses the request handler with the most

      points and passes over the control.</para>

      <para>Custom request handlers for special purposes just need to

      implement the

      <interfacename>\TYPO3\FLOW3\MVC\RequestHandlerInterface</interfacename>.

      All classes implementing that interface are automatically registered and

      will be considered while resolving a suitable request handler.</para>

    </section>

    <section>

      <title>Request Builder</title>

      <para>When a request handler receives a raw request, it needs to build a

      request object which can be passed to the dispatcher and later to the

      controller. The request building delegated to a request builder which

      can build the required request type (ie. web, CLI etc.).</para>

      <para>The building process mainly consists of</para>

      <procedure>

        <step>

          <para>create a new request object</para>

        </step>

        <step>

          <para>set some request-type specific parameters (like the request

          URI for a web request)</para>

        </step>

        <step>

          <para>determine and set the responsible controller, action and

          action arguments</para>

        </step>

      </procedure>

      <para>Especially the last step is important and requires some more or

      less complex routing in case of web requests.</para>

    </section>

    <section>

      <title>Request Dispatcher</title>

      <para>The final task of the MVC framework consists in dispatching the

      request to the controller specified in the request object. Dispatching

      means that the request and response object is passed to the controller

      specified in the request object and after the controller did its job,

      control is returned to the request handler which eventually sends the

      response.</para>

      <para>The dispatch method itself is a loop which tries to invoke a

      controller until a flag in the request object indicates that the request

      has been dispatched. In most cases this loop has only one cycle: the

      action method specified in the request is called and the action

      controller automatically sets the <varname>dispatched</varname> flag

      which leads to exiting the dispatch loop. However, when the controller

      wants to forward or redirect the request to another controller or

      action, the respective information is written to the request object and

      the <varname>dispatched</varname> flag remains unset. Therefore the

      dispatcher calls the next controller which hopefully can finally process

      the request and exits the dispatch loop.</para>

      <para>The dispatcher comes with a safeguard which assures that the

      dispatching process does not end up in an endless loop.</para>

    </section>

    <section>

      <title>Request Types</title>

      <para>FLOW3 supports the most important request types out of the box.

      Additional request types can easily be implemented by implementing the

      <interfacename>\TYPO3\FLOW3\MVC\RequestInterface</interfacename> or

      extending the <classname>\TYPO3\FLOW3\MVC\Request</classname> class and

      registering a request handling which can handle the new request type

      (and takes care of building the request object). Here are the request

      types which come with the default FLOW3 distribution:</para>

      <section>

        <title>Web Request / Response</title>

        <para>Web requests are the most common request types. Additional to

        the common request functionality, this request type delivers

        information about the request method, request URI and the base

        URI.</para>

      </section>

      <section>

        <title>CLI Request / Response</title>

        <para>Requests from the command line are recognized by the used SAPI

        (Server Application Programming Interface).</para>

      </section>

    </section>

  </section>

  <section xml:id="flow3.mvcframework.controller">

    <title>Controller</title>

    <para>The main responsibility of a controller is to process a request and

    deliver a meaningful response. The

    <interfacename>\TYPO3\FLOW3\MVC\Controller\ControllerInterface</interfacename>

    therefore only contains two methods:</para>

    <programlisting language="php">/**

 * Checks if the current request type is supported by the controller.

 *

 * @param \TYPO3\FLOW3\MVC\RequestInterface $request The current request

 * @return boolean TRUE if this request type is supported, otherwise FALSE

 */

public function canProcessRequest(\TYPO3\FLOW3\MVC\RequestInterface $request);

/**

 * Processes a general request. The result can be returned by altering the given response.

 *

 * @param \TYPO3\FLOW3\MVC\RequestInterface $request The request object

 * @param \TYPO3\FLOW3\MVC\ResponseInterface $response The response, modified by the controller

 * @return void

 * @throws \TYPO3\FLOW3\MVC\Exception\UnsupportedRequestTypeException if the controller doesn't support the current request type

 */

public function processRequest(\TYPO3\FLOW3\MVC\RequestInterface $request, \TYPO3\FLOW3\MVC\ResponseInterface $response);

</programlisting>

    <para>However, only few applications will implement the whole request

    processing logic themselves. Most of the time you'll be extending the

    Action Controller.</para>

    <section>

      <title>Action Controller</title>

      <para>The

      <classname>\TYPO3\FLOW3\MVC\Controller\ActionController</classname>

      processes a request by calling action methods. Actions are the

      foundation of your application's workflow and logic. Which action is

      called is usually determined by the URI as you have already seen in the

      short hello world example.</para>

      <section>

        <title>Initialization Methods</title>

        <para>Before an action method is called, the view, validation and

        arguments are initialized. The following methods can be extended or

        overloaded to hook into this initialization process:</para>

        <itemizedlist>

          <listitem>

            <para><methodname>initializeView()</methodname> is called in order

            to resolve, set and initialize a view which matches the current

            action.</para>

          </listitem>

          <listitem>

            <para><methodname>initializeAction()</methodname> is called after

            the view has been initialized and the automatic registration of

            arguments is done. At that point, the argument's values are still

            empty and have not been validated.</para>

          </listitem>

          <listitem>

            <para><methodname>initializeFooAction()</methodname> where

            <methodname>Foo</methodname> is the name of the action, is called

            only before an action of that name is called.</para>

          </listitem>

        </itemizedlist>

        <para>Action arguments are usually registered automatically (see

        below). If you wish to register additional arguments manually, you may

        do that in one of the <methodname>initialize*Action()</methodname>

        methods.</para>

      </section>

      <section>

        <title>Configuration</title>

        <para>The settings of the package containing your controller are

        automatically injected into the action controller and can be accessed

        through the <varname>$this-&gt;settings</varname> variable. Please

        note that this variable contains all settings of the package as an

        array, not only settings specific to your controller.</para>

        <para>You should not modify the settings array because any information

        you'd add would be lost anyway and is invisible to other parts of your

        application.</para>

      </section>

      <section>

        <title>Supported Request Types</title>

        <para>The action controller generally supports any kind of request,

        which means that theoretically you need only one controller for web

        and CLI requests. In practice you might want to structure your

        application so that a controller is responsable for only one request

        type. If that is the case, you can define the supported request types

        by setting the <property>supportedRequestTypes</property> property of

        your class:</para>

        <example>

          <title>Defining the supported request types</title>

          <programlisting language="php">/**

 * My web-specific controller

 */

class StandardController extends \TYPO3\FLOW3\MVC\Controller\ActionController {

   /**

    * @var array

    */

   protected $supportedRequestTypes = array('TYPO3\FLOW3\MVC\Web\Request');

</programlisting>

        </example>

      </section>

      <section>

        <title>Arguments</title>

        <para>An action usually needs some more information about what it's

        supposed to do. This information comes in form of GET or POST

        arguments in case of a web request or via command line options if

        we're dealing with a CLI request. Because there are even more ways to

        pass information to an action and because this information needs

        special care to assure a secure application, these arguments are

        abstracted by FLOW3 in form of controller arguments.</para>

        <para>The basic rule in FLOW3 is: an action method only gets those

        arguments it asked for which have always values which are allowed for

        the declared data type. Therefore arguments need to be registered and

        it is not possible to access PHP's superglobals

        <varname>$_GET</varname> and <varname>$_POST</varname>

        directly.</para>

        <para>Fortunately argument registration is very easy in FLOW3. It's

        just a matter declaring the arguments in your action method

        signature:</para>

        <example>

          <title>Declaring arguments in an action method</title>

          <programlisting language="php">/**

 * An example action method

 *

 * @param string $emailAddress Some email address

 * @param string $streetName Some street name

 * @param \TYPO3\Foo\Model\Customer $customer A customer object

 * @return void

 */

public function exampleAction($emailAddress, $streetName, \TYPO3\Foo\Model\Customer $customer) {

}

</programlisting>

        </example>

        <para>FLOW3 will automatically register the arguments

        <parameter>$emailAddress</parameter>,

        <parameter>$streetName</parameter> and

        <parameter>$customer</parameter>. Their expected data types are

        <classname>Text</classname>, <classname>Text</classname> and

        <classname>\TYPO3\Foo\customer</classname> respectively.</para>

        <para>In essence this means that if you send a GET parameter

        <parameter>emailAddress</parameter> with your request, it will end up

        in <parameter>$emailAddress</parameter> if it is a valid

        <classname>Text</classname> (which means: no HTML, no JavaScript, no

        danger). Even the <parameter>$customer</parameter> argument will

        contain a real <classname>Customer</classname> object if enough

        information has been sent with the request.</para>

      </section>

      <section>

        <title>Argument Validation</title>

        <para>All arguments passed to the action methods will automatically

        validated through their base validation rules defined in the

        respective models. Additional validation rules can be defined by using

        the <varname>@validate</varname> annotation. The syntax is similar to

        a regular <varname>@validate</varname> declaration with the addition

        that the argument name must be specified:</para>

        <example>

          <title>Additional validation rules in an action method</title>

          <programlisting language="php">/**

 * An example action method

 *

 * @param string $emailAddress Some email address

 * @param string $streetName Some street name

 * @param \TYPO3\Foo\Model\Customer $customer A customer object

 * @return void

 * @validate $emailAddress EmailAddress

 * @validate $streeName Alphanumeric, StringLength(minimum = 5, maximum = 100)

 * @validate $customer TYPO3\Foo\Validator\PlatinumCustomerValidator

 */

public function exampleAction($emailAddress, $streetName, \TYPO3\Foo\Model\Customer $customer) {

}

</programlisting>

        </example>

        <para>In a few situations it is necessary to disable validation for a

        single argument, for example if an object needs to passed between

        actions while it is beeing edited and therefore is knowingly in an

        incomplete state. In these cases validation can be swtiched off

        through the <literal>@dontvalidate</literal> annotation:</para>

        <programlisting language="php">/**

 * An example edit action method

 *

 * @param \TYPO3\Foo\Model\Customer $customer A customer object

 * @return void

 * @dontvalidate $customer

 */

public function editAction(\TYPO3\Foo\Model\Customer $customer) {

}</programlisting>

      </section>

      <section>

        <title>Action Methods</title>

        <para>$this-&gt;indexActionMethodName</para>

        <para/>

      </section>

    </section>

    <section>

      <title>Other Controllers</title>

      <section>

        <title>Abstract Controller</title>

        <para/>

      </section>

      <section>

        <title>Request Handling Controller</title>

        <para/>

      </section>

      <section>

        <title>Standard Controller</title>

        <para/>

      </section>

      <section>

        <title>Not Found Controller</title>

        <para>The

        <classname>TYPO3\FLOW3\MVC\Controller\NotFoundController</classname> is

        used whenever no other controller could be resolved which would match

        the current request. It displays a generic "404 Page Not Found"

        message.</para>

        <para>It is possible to define your own custom controller which is

        used in these cases. Just specify the object name in the FLOW3

        settings.</para>

      </section>

    </section>

  </section>

  <section xml:id="flow3.mvcframework.view">

    <title>View</title>

    <para/>

    <section>

      <title>Template View</title>

      <para/>

    </section>

    <section>

      <title>Special Views</title>

      <section>

        <title>Standard View</title>

        <para/>

      </section>

      <section>

        <title>Empty View</title>

        <para/>

      </section>

    </section>

  </section>

  <section xml:id="flow3.mvcframework.helpers">

    <title>Helpers</title>

    <para/>

  </section>

  <section xml:id="flow3.mvcframework.model">

    <title>Model</title>

    <para/>

  </section>

  <section xml:id="flow3.mvcframework.routing">

    <title>Routing</title>

    <para>As explained in the beginning of this chapter, in FLOW3 the

    dispatcher passes the request to a controller which then calls the

    respective action. But how to tell, what controller of what package is the

    right one for the current request? This is were the routing framework

    comes into play.</para>

    <section>

      <title>Router</title>

      <para>The request builder asks the router for the correct package,

      controller and action. For this it passes the current request path to

      the routers <methodname>match</methodname> method. The router then

      iterates through all configured routes and invokes their

      <methodname>matches</methodname> method. The first route that matches,

      determines which action will be called with what parameters.</para>

      <para>The same works for the opposite direction: If a link is generated

      the router calls the <methodname>resolve</methodname> method of all

      routes until one route can return the correct URI for the specified

      arguments.</para>

      <para><note>

          <para>If no matching route can be found, the

          <methodname>indexAction</methodname> of the

          <classname>StandardController</classname> of the

          <package>FLOW3</package> package is called.</para>

        </note></para>

    </section>

    <section>

      <title>Route</title>

      <para>A route describes the way from your browser to the controller -

      and back.</para>

      <para>With the <emphasis>URI pattern</emphasis> you can define how a

      route is represented in the browsers address bar. By setting

      <emphasis>defaults</emphasis> you can specify package, controller and

      action that should apply when a request matches the route. Besides you

      can set arbitrary default values that will be available in your

      controller. They are called <emphasis>defaults</emphasis> because you

      can overwrite them by so called <emphasis>dynamic route

      parts</emphasis>.</para>

      <para>But let's start with an easy example:<example>

          <title>Simple route - Routes.yaml</title>

          <programlisting language="yaml">--

  name: 'Homepage'

  uriPattern: ''

  defaults:

    '@package': Demo</programlisting>

        </example><note>

          <para>name is optional, but it's recommended to set a name for all

          routes to make debugging easier.</para>

        </note></para>

      <para>If you insert these lines at the beginning of the file

      <filename>Configurations/Routes.yaml</filename>, the

      <methodname>indexAction</methodname> of the

      <classname>StandardController</classname> in your

      <package>Demo</package> package will be called when you open up the

      homepage of your FLOW3 installation

      (<uri>http://localhost/).</uri></para>

      <para><note>

          <para>You don't have to specify action and controller in this

          example as the <methodname>indexAction</methodname> of the

          <classname>StandardController</classname> is always called by

          default.</para>

        </note></para>

      <section>

        <title>URI pattern</title>

        <para>The URI pattern defines the appearance of the URI. In a simple

        setup the pattern only consists of <emphasis>static route

        parts</emphasis> and is equal to the actual URI (without protocol and

        host).</para>

        <para>In order to reduce the amount of routes that have to be created,

        you are allowed to insert markers, so called <emphasis>dynamic route

        parts</emphasis>, that will be repaced by the routing framework. You

        can even mark route parts <emphasis>optional</emphasis>.</para>

        <para>But first things first.</para>

        <section>

          <title>Static route parts</title>

          <para>A static route part is really simple - it will be mapped

          one-to-one to the resulting URI without transformation.</para>

          <para>Let's create a route that calls the listAction of the

          CustomerController when browsing to

          <uri>http://localhost/my/demo</uri>:<example>

              <title>Simple route with static route parts -

              Configuration/Routes.yaml</title>

              <para><programlisting language="yaml">--

  name: 'Static demo route'

  uriPattern: 'my/demo'

  defaults:

    '@package':    Demo

    '@controller': Customer

    '@action':     list</programlisting></para>

            </example></para>

        </section>

        <section>

          <title>Dynamic route parts</title>

          <para>Dynamic route parts are enclosed in curly brackets and define

          parts of the URI that are not fixed.</para>

          <para>Let's add some dynamics to the previous example:<example>

              <title>Simple route with static and dynamic route parts -

              Configuration/Routes.yaml</title>

              <para><programlisting language="yaml">--

  name: 'Dynamic demo route'

  uriPattern: 'my/demo/{@action}'

  defaults:

    '@package':    Demo

    '@controller': Customer</programlisting></para>

            </example>Now <uri>http://localhost/my/demo/list</uri> calls the

          <methodname>listAction</methodname> just like in the previous

          example.</para>

          <para>With <uri>http://localhost/my/demo/index</uri> you'd invoke

          the <methodname>indexAction</methodname> and so on.</para>

          <para><note>

              <para>It's not allowed to have successive dynamic route parts in

              the URI pattern because it wouldn't be possible to determine the

              end of the first dynamic route part then.</para>

            </note></para>

          <para>The @-prefix should reveal that action has a special meaning

          here. Other predefined keys are @package, @subpackage, @controller

          and @format. But you can use dynamic route parts to set any kind of

          arguments:<example>

              <title>dynamic parameters - Configuration/Routes.yaml</title>

              <programlisting language="yaml">--

  name: 'Dynamic demo route'

  uriPattern: 'clients/{sortOrder}.{@format}'

  defaults:

    '@package':    Demo

    '@controller': Customer

    '@action':     list</programlisting>

            </example></para>

          <para>Browsing to <uri>http://localhost/clients/descending.xml</uri>

          would call the <methodname>listAction</methodname> in your

          <classname>Customer</classname> controller and the request argument

          "sortOrder" had the value of "descending".</para>

          <para>By default, dynamic route parts match anything apart from

          empty strings. If you have more specialized requirements you can

          create your custom route part handlers.</para>

        </section>

        <section>

          <title>Route part handler</title>

          <para>Route part handlers are classes that implement

          <interfacename>TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePartInterface</interfacename>.

          But for most cases it will be sufficient to extend

          <classname>TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePart</classname> and

          overwrite the methods <methodname>matchValue</methodname> and

          <methodname>resolveValue</methodname>.</para>

          <para>Let's have a look at the (very simple) route part handler of

          the blog example:<example>

              <title>BlogRoutePartHandler.php</title>

              <programlisting language="php">class BlogRoutePartHandler extends \TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePart {

        /**

         * While matching, converts the blog title into an identifer array

         *

         * @param string $value value to match, the blog title

         * @return boolean TRUE if value could be matched successfully, otherwise FALSE.

         */

        protected function matchValue($value) {

                if ($value === NULL || $value === '') return FALSE;

                $this->value = array('__identity' => array('name' => $value));

                return TRUE;

        }

        /**

         * Resolves the name of the blog

         *

         * @param \TYPO3\Blog\Domain\Model\Blog $value The Blog object

         * @return boolean TRUE if the name of the blog could be resolved and stored in $this->value, otherwise FALSE.

         */

        protected function resolveValue($value) {

                if (!$value instanceof \TYPO3\Blog\Domain\Model\Blog) return FALSE;

                $this->value = $value->getName();

                return TRUE;

        }

}</programlisting>

            </example></para>

          <para>The corresponding route might look like this:<example>

              <title>Route with route part handlers -

              Configuration/Routes.yaml</title>

              <programlisting language="yaml">--

  name: 'Blog route'

  uriPattern: 'blogs/{blog}/{@action}'

  defaults:

    '@package':    Blog

    '@controller': Blog

  routeParts:

    blog:

      handler: TYPO3\Blog\RoutePartHandlers\BlogRoutePartHandler</programlisting>

            </example></para>

          <para>Have a look at the blog example for a working setup.</para>

        </section>

        <section>

          <title>Optional route parts</title>

          <para>By putting one or more route parts in round brackets you mark

          them optional. The following route matches

          <uri>http://localhost/my/demo/ </uri>and

          <uri>http://localhost/my/demo/list.html</uri>.</para>

          <example>

            <title>Route with optional route parts -

            Configuration/Routes.yaml</title>

            <para><programlisting language="yaml">--

  name: 'Dynamic demo route'

  uriPattern: 'my/demo(/{@action}.html)'

  defaults:

    '@package':    'Demo'

    '@controller': 'Customer'

    '@action':     'list'</programlisting></para>

          </example>

          <note>

            <para><uri>http://localhost/my/demo/list</uri> won't match here,

            because either all optional parts have to match - or none.</para>

          </note>

          <note>

            <para>You have to define default values for all optional dynamic

            route parts.</para>

          </note>

        </section>

        <section>

          <title>Case sensitivity</title>

          <para>By Default the case is not changed when creating URIs. The

          following example with a username of "Kasper" will result in

          <uri>http://localhost/Users/Kasper</uri><example>

              <title>Route with default case handling</title>

              <para><programlisting language="yaml">--

  uriPattern: 'Users/{username}'

  defaults:

    @package:    'Demo'

    @controller: 'Customer'

    @action:     'show'</programlisting></para>

            </example></para>

          <para>You can change this behavior for routes and/or dynamic route

          parts:<example>

              <title>Route with customised case handling</title>

              <para><programlisting language="yaml">--

  uriPattern: 'Users/{username}'

  defaults:

    @package:    'Demo'

    @controller: 'Customer'

    @action:     'show'

  toLowerCase: true

  routeParts:

    username:

      toLowerCase: false</programlisting></para>

            </example>This will change the default behavior for this route and

          reset it for the username route part. Given the same username of

          "Kasper" the resulting URI will now be

          <uri>http://localhost/users/Kasper</uri> (note the lower case "u" in

          "users").</para>

          <note>

            <para>The predefined route parts @package, @subpackage,

            @controller, @action and @format are an exception, they're always

            lower cased!</para>

          </note>

          <para>Matching of incoming URIs is always done case insensitive. So

          both "Users/Kasper" and "users/Kasper" will match, and the value of

          the dynamic part will never be changed. If you want to handle data

          coming in through dynamic route parts case-insensitive, you need to

          handle that in your own code.</para>

        </section>

      </section>

    </section>

    <section>

      <title>Subroutes</title>

      <para>For security reasons and to avoid confusion, only routes

      configured in your global configuration folder are active. But FLOW3

      supports what we call subroutes enabling you to provide custom routes

      with your package and reference them in the global routing setup.</para>

      <para>Imagine following routes in the <filename>Routes.yaml</filename>

      file inside your demo package:<example>

          <title>Demo Subroutes - Demo/Configuration/Routes.yaml</title>

          <programlisting language="yaml">--

  name: 'Customer routes'

  uriPattern: '/clients/{@action}'

  defaults:

    '@controller': Customer

--

  name: 'Standard routes'

  uriPattern: '/{@action}'

  defaults:

    '@controller': Standard

--

  name: 'Fallback'

  uriPattern: ''

  defaults:

    '@controller': Standard

    '@action':     index</programlisting>

        </example></para>

      <para>And in your global <filename>Routes.yaml</filename>:<example>

          <title>Referencing subroutes - Configuration/Routes.yaml</title>

          <programlisting language="yaml">--

  name: 'Demo subroutes'

  uriPattern: 'demo<DemoSubroutes>(.{@format})'

  defaults:

    '@package': Demo

    '@format':  html

  subRoutes:

    DemoSubroutes:

      package: Demo</programlisting>

        </example></para>

      <para>As you can see, you can reference subroutes by putting parts of

      the URI pattern in angle brackets (like <subRoutes>). With the

      subRoutes setting you specify where to load the subroutes from.</para>

      <para>Internally the ConfigurationManager merges toghether the main

      route with its subroutes:<example>

          <title>Composite routes</title>

          <programlisting language="yaml">--

  name: 'Demo subroutes :: Customer routes'

  uriPattern: 'demo/clients/{@action}(.{@format})'

  defaults:

    '@package': Demo

    '@format':  html

    '@controller': Customer

--

  name: 'Demo subroutes :: Standard routes'

  uriPattern: 'demo/{@action}(.{@format})'

  defaults:

    '@package': Demo

    '@format':  html

    '@controller': Standard

--

  name: 'Demo subroutes :: Fallback'

  uriPattern: 'demo(.{@format})'

  defaults:

    '@package': Demo

    '@format':  html

    '@controller': Standard

    '@action':     index</programlisting>

          <para>You can even reference multiple subroutes from one route -

          that will create one route for all possible combinations.</para>

        </example></para>

    </section>

  </section>

  <section xml:id="flow3.mvcframework.clirequests">

    <title>CLI request handling</title>

    <para>FLOW3's CLI request handling offers a comfortable and flexible way

    of calling code from the command line:</para>

    <para><command>php index.php [<replaceable>command</replaceable>]

    [<replaceable>options</replaceable>] [--]

    [<replaceable>arguments</replaceable>]</command></para>

    <para><replaceable>command</replaceable>,

    <replaceable>options</replaceable> and

    <replaceable>arguments</replaceable> are optional, with varying results.

    The command structure follows what is commonly accpeted on unixoid systems

    for CLI programs:<variablelist>

        <varlistentry>

          <term>command</term>

          <listitem>

            <para>If not given, the default controller of the FLOW3 package is

            used and it's index action is called. While this is an allowed

            call, it hardly makes sense (other than checking if FLOW basically

            works). If command is given then it is defined as

            <emphasis><replaceable>package</replaceable>

            [[<replaceable>sub1..N</replaceable>]

            <replaceable>controller</replaceable>

            <replaceable>action</replaceable>]</emphasis></para>

            <para>First part is always the package. If only the package is

            given, it's StandardController's index action is called.</para>

            <para>If at least three command parts are given, the last two

            sepcify controller and action. Anything in between specifys a sub

            package structure.<example>

                <title>Some FLOW3 CLI command specifications</title>

                <para><literal>testing cli run</literal> would call the "run"

                action of the "cli" controller in the "Testing" package</para>

                <para><literal>typo3cr admin setup foo</literal> would call

                the "setup" controller's "foo" action in the subpackage

                "admin" of the package "TYPO3CR"</para>

              </example></para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>options</term>

          <listitem>

            <para>Options are either short- or long-style. The first option

            detected ends collecting command parts. Here are some

            examples:<example>

                <title>Giving options to FLOW3 CLI requests</title>

                <para><literal>-o -f=value --a-long-option --with-spaces="is

                possible" --input file1 -o=file2 --event-this =

                works</literal></para>

              </example></para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>arguments</term>

          <listitem>

            <para>Arguments can follow and will be available to the called

            controller in the request object. To distinguish between

            <replaceable>command</replaceable> and

            <replaceable>arguments</replaceable> in cases where no

            <replaceable>options</replaceable> are given the seperator

            <literal>--</literal> must be used.</para>

          </listitem>

        </varlistentry>

      </variablelist></para>

  </section>

</chapter>