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:

This diagram outlines the collaboration between model, view and controller:

Figure 8.1. Model-View-Controller Pattern

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:

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 “Hello World!”. To begin with, we need to create some directories which contain the code of our FLOW3 package and eventually the controller class:

The StandardController class looks as simple as this (leaving out the very recommended comments):

namespace F3\Demo\Controller;

class StandardController extends \F3\FLOW3\MVC\Controller\ActionController {
	public function indexAction() {
		return 'Hello World!';
	}
}

Provided that the document root of your local server points to FLOW3's Web/ directory, you will get the following output when calling the URI http://localhost/demo/:

Hello World!

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:

The view's code is equally trivial:

namespace F3\Demo\View\Standard;

class Index extends \F3\FLOW3\MVC\View\AbstractView {
	public function render() {
		return 'Hello World from your view!';
	}
}

Finally our action controller needs a little tweak to return the rendered view instead of shouting “Hello World!” itself:

namespace F3\Demo\Controller;

class StandardController extends \F3\FLOW3\MVC\Controller\ActionController {
	public function indexAction() {
		return $this->view->render();
	}
}

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 Fluid, FLOW3's powerful templating engine which allows you to write views in plain HTML and still have all the power like loops and conditions.

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:

This sample directory layout demonstrates the above rules:

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.

FLOW3 provides a standard way of resolving the URI to your MVC-Objects.

Say, you want to see the list of customers (based on the file-structure-example above). The URI to get the list would be: http://localhost/demo/customer/list.html or just http://localhost/demo/customer/list.

This URI will be resolved into the package-name (Demo), controller-name (Customer), action-name(list) and format-name (html - which is the default format).

Depending on that, the controller \F3\Demo\Controller\CustomerController (pattern: 'F3\@package\Controller\@controllerController') and its method listAction() will be used. The corresponding view is \F3\Demo\View\CustomerList (Pattern: 'F3\@package\View\@controller@action@format').

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 \F3\Demo\View\Customer\ListXML. To see the output of this new view, just use the URI http://localhost/demo/customer/list.xml.

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:

Figure 8.2. Example of a Web Request-Response Workflow

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.

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.

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.

Custom request handlers for special purposes just need to implement the \F3\FLOW3\MVC\RequestHandlerInterface. All classes implementing that interface are automatically registered and will be considered while resolving a suitable request handler.

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.).

The building process mainly consists of

Especially the last step is important and requires some more or less complex routing in case of web requests.

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.

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 dispatched 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 dispatched flag remains unset. Therefore the dispatcher calls the next controller which hopefully can finally process the request and exits the dispatch loop.

The dispatcher comes with a safeguard which assures that the dispatching process does not end up in an endless loop.

FLOW3 supports the most important request types out of the box. Additional request types can easily be implemented by implementing the \F3\FLOW3\MVC\RequestInterface or extending the \F3\FLOW3\MVC\Request 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:

The \F3\FLOW3\MVC\Controller\ActionController 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.

/**
 * My web-specific controller
 */
class StandardController extends \F3\FLOW3\MVC\Controller\ActionController {

   /**
    * @var array
    */
   protected $supportedRequestTypes = array('F3\FLOW3\MVC\Web\Request');

/**
 * An example action method
 *
 * @param string $emailAddress Some email address
 * @param string $streetName Some street name
 * @param F3\Foo\Model\Customer $customer A customer object
 * @return void
 */
public function exampleAction($emailAddress, $streetName, \F3\Foo\Model\Customer $customer) {
   
}

/**
 * An example action method
 *
 * @param string $emailAddress Some email address
 * @param string $streetName Some street name
 * @param F3\Foo\Model\Customer $customer A customer object
 * @return void
 * @validate $emailAddress EmailAddress
 * @validate $streeName Alphanumeric, StringLength(minimum = 5, maximum = 100)
 * @validate $customer F3\Foo\Validator\PlatinumCustomerValidator
 */
public function exampleAction($emailAddress, $streetName, \F3\Foo\Model\Customer $customer) {
   
}

/**
 * An example edit action method
 *
 * @param F3\Foo\Model\Customer $customer A customer object
 * @return void
 * @dontvalidate $customer
 */
public function editAction(\F3\Foo\Model\Customer $customer) {
   
}

The request builder asks the router for the correct package, controller and action. For this it passes the current request path to the routers match method. The router then iterates through all configured routes and invokes their matches method. The first route that matches, determines which action will be called with what parameters.

The same works for the opposite direction: If a link is generated the router calls the resolve method of all routes until one route can return the correct URI for the specified arguments.

A route describes the way from your browser to the controller - and back.

With the URI pattern you can define how a route is represented in the browsers address bar. By setting defaults 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 defaults because you can overwrite them by so called dynamic route parts.

But let's start with an easy example:

--
  name: 'Homepage'
  uriPattern: ''
  defaults:
    '@package': Demo

If you insert these lines at the beginning of the file Configurations/Routes.yaml, the indexAction of the StandardController in your Demo package will be called when you open up the homepage of your FLOW3 installation (http://localhost/).

--
  name: 'Static demo route'
  uriPattern: 'my/demo'
  defaults:
    '@package':    Demo
    '@controller': Customer
    '@action':     list

--
  name: 'Dynamic demo route'
  uriPattern: 'my/demo/{@action}'
  defaults:
    '@package':    Demo
    '@controller': Customer

--
  name: 'Dynamic demo route'
  uriPattern: 'clients/{sortOrder}.{@format}'
  defaults:
    '@package':    Demo
    '@controller': Customer
    '@action':     list

class BlogRoutePartHandler extends \F3\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 \F3\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 \F3\Blog\Domain\Model\Blog) return FALSE;
		$this->value = $value->getName();
		return TRUE;
	}
}

--
  name: 'Blog route'
  uriPattern: 'blogs/{blog}/{@action}'
  defaults:
    '@package':    Blog
    '@controller': Blog
  routeParts:
    blog:
      handler: F3\Blog\RoutePartHandlers\BlogRoutePartHandler

--
  name: 'Dynamic demo route'
  uriPattern: 'my/demo(/{@action}.html)'
  defaults:
    '@package':    'Demo'
    '@controller': 'Customer'
    '@action':     'list'

--
  uriPattern: 'Users/{username}'
  defaults:
    @package:    'Demo'
    @controller: 'Customer'
    @action:     'show'

--
  uriPattern: 'Users/{username}'
  defaults:
    @package:    'Demo'
    @controller: 'Customer'
    @action:     'show'
  toLowerCase: true
  routeParts:
    username:
      toLowerCase: false

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.

Imagine following routes in the Routes.yaml file inside your demo package:

--
  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

And in your global Routes.yaml:

--
  name: 'Demo subroutes'
  uriPattern: 'demo<DemoSubroutes>(.{@format})'
  defaults:
    '@package': Demo
    '@format':  html
  subRoutes:
    DemoSubroutes:
      package: Demo

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.

Internally the ConfigurationManager merges toghether the main route with its subroutes:

--
  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