1. Introduction
    1. About Agavi
    2. MVC in Agavi
    3. Overview of Agavi
    4. Overview of Application Execution Flow
    5. A Word About Actions
    6. Application filesystem layout
    7. Overview of application configuration
  2. Setting Up The Initial Application
    1. Installing Agavi
    2. Creating an Agavi Project
    3. Finishing The Setup
    4. Finishing The Basic Setup
    5. Installing a New Copy of Your Application
  3. Adding First Code
    1. Creating A New module
    2. Creating A New Action
    3. Tying Things Together — An Introduction To Routing
    4. Fixing The Bloggie Routing
    5. Accessing Request Parameters and Validation Basics
    6. Handling Validation Errors
  4. Putting The M in MVC
    1. Creating A New Model
    2. Adapting The Actions and Views
    3. Custom Validators
  5. Polishing It Up
    1. Layers and Layouts
    2. Applying Our Layout
    3. What Are Slots?
    4. Adding The Post's Title To The URL
    5. Routing Callbacks
    6. Using Callbacks for the Title in URLs
  6. Connecting to a database
    1. The Database Manager
  7. Handling Output Variants
    1. Output Types
    2. Exception Templates
    3. Generating an RSS Feed
  8. Form Processing
    1. Adding a Post
    2. Editing a Post
    3. The Form Population Filter (FPF)
  9. Creating a User Authentication System
  10. Adding To The Master Template

Routing Callbacks

A routing callback is a class that can intercept certain routing actions and modify parameters or other options. It is notified when


  • A route is generated
  • A route has been matched
  • An attempt was made to match a route but it has not been matched

A routing callback is not notified if maching stopped before there was an attempt to match the route. The routing notifies the callbacks by calling the appropriate methods on the callback - AgaviRoutingCallback::onGenerate() when the route is being generated, AgaviRoutingCallback::onMatched() when the route matched, AgaviRoutingCallback::onNotMatched() in case an attempt to match the route failed. A route may define any number of callbacks that are executed in the order they're defined in, however excessive use of callbacks can slow your routing.

AgaviRoutingCallback::onGenerate()

This method is called when the route is about to be reverse generated into an URL. It can be used to modify the parameters and options passed to the call of AgaviRouting::gen() by the user. This method can be used to turn objects into routing parameters, strip undesired characters from parameters etc. If this method returns false the url-snippet generated by this route is not generated.

AgaviRoutingCallback::onMatched()

This method is called when the regular expression of the route matched. It may inspect and modify any of the parameters extracted from the route or add new parameters. If this method returns false, the route counts as not matched and all parameters modified will be reset. The callback may modify the execution container as well. If the callback returns a response object the resulting response is sent immediatly without any action execution. This behavior can be used for quick redirects.

AgaviRoutingCallback::onNotMatched()

This method is called when the regular expression of the route did not match. The callback may modify the execution container as well. If the callback returns a response object the resulting response is sent immediatly without any action execution. This behavior can be used for quick redirects.

Adding Callbacks to a Route

A list of callbacks may be added to a route by using the <callbacks> tag. The class for the callback must either be included before the routing is executed or more preferably added to the global autoload definition. Any number of parameters may be passed to the callback by adding <ae:parameter> tags as required.

<route name=".post" pattern="^/(post:\d+)(-{title:[-\w]+})?" action="Post">
  <callbacks>
    <callback class="PostRoutingCallback" />
  </callbacks>
  <route name=".show" pattern="^$" action=".Show" />
</route>

Routing Values

An AgaviRoutingValue is a value object that encapsulates all parameters passed to the routing. It's purpose is to store some meta information about the parameter value, mainly whether it's been encoded or not. All parameters passed to AgaviRoutingCallback::onGenerate() are wrapped in AgaviRoutingValue objects and all parameters changed by this method must be wrapped as well.