This chapter focuses on how to use user input in Agavi actions and views. We don't go into input validation as the validation in Agavi works in such a way that you can turn it on later without touching the code in actions or views. Just remember that in real life you should never use any un-validated user input.

All the input from the user like $_GET and $_POST arrays in the web context is stored into AgaviRequestDataholder (in the web context AgaviWebRequestDataHolder but you don't have to worry about the actual implementation) object that's given to the action's execute method as an argument. Depending on your validation settings this object has either all input or just the input that has passed validation (see chapter Validation to learn more about different validation set-ups). For added security PHP's superglobals like $_GET and $_POST are emptied entirely. This is to keep developers from accidentally using insecure data. Agavi also removes so-called magic quotes from the input should that feature be enabled in your PHP set-up.

class Products_EditAction extends WebShopBaseAction
{
  // route pattern /product/(id:\d+)/edit
  // eg. www.example.com/product/123/edit to edit prd no 123

  public function executeWrite(AgaviRequestDataHolder $rd)
  {
    $prdId = $rd->getParameter('prdid');

    $product = $this->getContext()->getModel('Product', 'Products', array('id'=>'$prdId));
    $product->setName($rd->getParameter('prdname');
    $product->save();

    return 'Success';
  }

This simple example shows us two important type of input - input coming directly from the user (submitted via an HTML form perhaps) and implicit parameters from the route (URL). Both input types are accessed with getParameter(name, default) of the AgaviRequestDataHolder.

In web context cookies, HTTP headers and uploaded files are accessed just as easily with their respective access methods getCookie, getHeader and getFile.

If we take the previous Shop-example in section 6.2, we notice that we have to specify the id-parameter every time, otherwise the route will not match. So how do we add optional parts to the route?

Because the route pattern is a regular expression, this is done the same way optional parts are done in regular expressions: with the ?-quantifier.

<route name="viewproduct" pattern="^/products(/{id:\d+})?$" module="Shop" action="ViewProduct" />

The difference between this route and the previous one is that now the slash and the id -parameters are optional. That is, the request http://host.com/products would also run the Shop.ViewProduct action, but the id-parameter would be undefined. Your action can then check if the id request parameter is null, and if so show a listing of, say, all products.

The default-element specifies values that should be used if a parameter is not supplied. This also applies for generating the route even if the parameter is not optional. For instance, we have a route like this:

<route name="viewproduct" pattern="^/products(/{id:\d+})(/{lang:[a-z]{2})?$" module="Shop" action="ViewProduct">
  <defaults>
    <default for="lang">en</default>
  </defaults>
</route>

indicates that if we do not specify a value for the lang-parameter (specified with the for="lang" -attribute), the default will be set to "en". Likewise, if we would remove the ?-quantifier from the end of the pattern and generate a route to viewproduct but do not specify the lang-parameter, it will use the default "en".

When using @@optional parts@@, you almost always need additional characters before and after the actual parameters. For that, you can use pre- and postfixes.

To use them, you enclose the name:expression part in curly braces, and outside of these, you define the pre- and postfixes that should not be included in a matched value:

^/uri(/pre-part-{varname:regexp}-post-part)$

Let's look at a more complicated example from the Sample Application:

<route name="search_engine_spam" pattern="^/products(/buy-cheap-{name:[\S\s]+}-at-agavi-dot-org)?/(id:\d+)" module="Default" action="SearchEngineSpam">
  <defaults>
    <default for="name">/buy-cheap-{chainsaws}-at-agavi-dot-org</default>
  </defaults>
</route>

This would match the request http://host.com/products/37 and http://host.com/products/buy-cheap-whatever-at-agavi-dot-org/37. The inner part is optional, and for Search Engine Optimization (or, in this case, stupid spamming) only.

The <default> here indicates that if we do not supply the "/buy-cheap-whatever-at-agavi-dot-org", it will set it to "/buy-cheap-chainsaws-at-agavi-dot-org", thus setting the name-parameter to "chainsaws", and id to null. (see @@previous section@@)

The ignores-section specifies parameters that affect the routing or output types, but are not set as request parameters. From the sample application:

<route pattern="^/({locale:[a-z]{2}(_[A-Z]{2})?})" stop="false" imply="true" cut="true" locale="${locale}@currency=GBP" callback="AgaviSampleAppLanguageRoutingCallback">
  <ignores>
    <ignore>locale</ignore>
  </ignores>
</route>

If the locale-parameter is set here, we use the route to set the application locale to the value specified. The ignore-section means that the parameter specified will not be available as a request parameter later on.

Routing callbacks are user-defined classes that run when Agavi tests the route for matches. The class has to implement methods that Agavi call, and these methods would return true or false depending on if the route matching is to succeed or fail.

onMatched is called when the route matches. This method can then return either true to indicate that it did indeed match, or false to indicate that even though the pattern itself matches, the route should fail.

onNotMatched is similarly called for routes that do not match the pattern, and likewise can return true to indicate that the pattern should match nevertheless, or false to indicate that ithe route should fail.

onGenerate is called when the routing engine generates an URI for the route, and can modify parameters and return true or false indicating wether this fragment should be in the route at all.

Imagine you have a big application with tens or hundreds of actions. Imagine adding all those into routing.xml one by one in the <routes> -section. It would be very ineffective to parse through all those routes in order to find the correct route. Introducing... subroutes!

Subroutes are routes that are defined under other routes. Let us explain through an example:

<route name="blog" pattern="^/blog" module="Default" action="Blog">
  <route name=".index" pattern="^/$" action=".Index" />
  <route name=".article" pattern="^/(id:\d+)(-{title:\S+})?$" action=".ShowArticle" />
</route> 

This would not run the action Blog in the module Default for the request http://host.com/blog. Why not? Because the request cannot be anchored at the end of the pattern, as the pattern has children. That is, to run the Blog.Index -action, you would have to use the request http://host.com/blog/ (note the slash), and to run the Blog.ShowArticle with the id and title -parameters set, you would have to use the request http://host.com/blog/151-Agavi_rocks. This way you only have to define "top level" routes for your main actions, and you can use subroutes to define routes to actions that are conceptually below the "top level" actions, making parsing of the route much faster.

Routing can do more -- like match against other sources, or do things other than setting module and action. An example:

Because this is a MVC-framework, the data produced in the model should be view-independent. That is, the same data could be rendered as XHTML or a PDF or whatever you can imagine. You can define the output type by setting the output_type -attribute for the route:

<route name="rss" pattern="/rss$" output_type="rss" stop="false" cut="true" />

As you can see, the pattern is only anchored at the end. On a match, routing execution will not stop, and the matched portion ("/rss") will be cut from the route for the following tests against the remaining routes.

Now let's say your application also has fancy AJAX features, and you return the data in JSON format. You can use the exact same URLs for "normal" and AJAX requests, since there is a difference: most AJAX frameworks send special headers along with the request. We can use that to automatically set the output type for these to JSON:

<route pattern="text/javascript" source="_SERVER[HTTP_ACCEPT]" output_type="json" stop="false" />

Here, if the HTTP Accept header contains text/javascript (which it does if you make an XMLHTTPRequest using Prototype or Mootools or Dojo), then the output type will be set to "json". We are operating on a different source, $_SERVER, that allows to access it's members directly.

To generate routes in templates or actions, you use the AgaviRouting-class which returns the URI or route as a string. You must use the name -attribute for the routes in order for the AgaviRouting-class to know which route to generate, unless you are generating a route to the same route the user currently is at. The way to generate a route is

$ro->gen(routename[, array parameters[, array options]])

So if we take our blog-route from section 6.2.6 and want to generate a route to /blog/151/Agavi_rocks, we would use

$ro->gen("blog.article", array('id' => 151, 'title' => 'Agavi_rocks'));

This would generate a relative URI, thus won't include the protocol (http/https/whatever) nor the host name. To generate a complete URI to the document with the same protocol that the user used, you set the "relative" option to false:

$ro->gen("blog.article", array('id' => 151, 'title' => 'Agavi_rocks'), array('relative' => false));

To generate a route to the same page the user is currently at, use null as the route name.

If the user has accessed the page with the HTTP-protocol and you need to generate a route to a super-secure location using HTTPS, you set the "protocol" option to "HTTPS". To generate a URI to the same route that the user is on but add an anchor (#foobar), use

$ro->gen(null, array(), array('fragment' => 'foobar'));