<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
  <title>The Definitive Guide to Agavi</title>

  <bookinfo>
    <releaseinfo>$Revision$</releaseinfo>

    <date>$Date$</date>
  </bookinfo>

  <preface id="preface">
    <title>Preface</title>

    <para>Welcome to the Agavi manual. This book tries to serve you as the
    definitive guide to the Agavi framework. It contains a "Getting Started"
    guide, a comprehensive introduction to the concept and usage of Agavi, and
    a reference manual that documents all aspects of the framework. A separate
    "Best Practices" book accompanies this guide. Also, there's the
    "Introduction to Agavi" book, which gives you an idea of the philosophy
    behind Agavi, and the way it works as a "big picture".</para>
  </preface>

  <chapter id="intro">
    <title>An Introduction</title>

    <section id="intro-agavi">
      <title>Agavi, a (Web) Application Framework</title>

      <section id="what-a-framework-is">
        <title>What a Framework Is</title>

        <para>A framework is a tool that takes the pain out of building
        software. It should implement all the things that are common to most
        applications: the things that otherwise would have to be re-done for
        each new software project. That way, it prevents you from having to
        "re-invent the wheel" each and every time, while at the same time
        providing shortcuts for common problems and tasks.</para>

        <para>While Agavi can, in theory, be used to build any type of
        application, its main focus lies in Web-based applications and Web
        services rather than standalone rich-client applications or daemons.
        That's because the internal execution flow is modeled around a typical
        HTTP request/response scenario, where a controller is invoked upon a
        request, and the resulting response is built and returned before
        execution ends, just like any other PHP application.</para>

        <para>Besides "doing the dishes" for you, a framework should also
        offer a very important factor during development: guidance. Agavi
        will, where necessary, actively prevent you from making the worst
        mistakes, keeping your code maintainable and giving you the comforting
        feeling that you're doing things the "right way."</para>
      </section>

      <section id="what-a-framework-should-do">
        <title>What a Framework Should Do</title>

        <section id="invent-the-wheel-only-once">
          <title>Invent The Wheel Only Once</title>

          <para>Agavi abstracts common problems, and provides you, the
          developer, with a central, flexible solution that has evolved from
          the experiences and input of many users, as well as a single point
          of implementation you can comfortably override with custom code to
          create application-specific behavior.</para>

          <para>As a result, you'll find yourself in the relaxing situation of
          not having to hack the framework core to achieve a certain goal.
          Often, a configuration parameter is all you need. And if not, the
          system's extreme extensibility guarantees that your custom
          implementation is only a couple of lines of code away - an important
          factor in the maintainability of an application, as it is not
          necessary to apply custom patches to the framework after each
          update.</para>
        </section>

        <section id="address-common-concerns">
          <title>Address Common Concerns</title>

          <para>Agavi comes with smart and versatile solutions to a great deal
          of problems that are often very difficult, time-consuming, or simply
          annoying to solve. Some of these include:</para>

          <para><simplelist>
              <member><emphasis role="bold">It helps you build and maintain
              clean URLs.</emphasis> Agavi's routing implementation can not
              only map request URLs to controllers, but also handles your web
              service requests, generates URLs for you, and much more. Read
              the chapter on routing for more information on advanced features
              such as route callbacks or how to read an HTTP Accept header and
              set an output type accordingly.</member>
            </simplelist></para>

          <para><simplelist>
              <member><emphasis role="bold">It validates your data and helps
              secure your code.</emphasis> Agavi can validate input submitted
              by the user, filter and normalize values, and make your
              application totally bullet-proof by only exposing validated data
              to your code, greatly lowering the risks of you or one of your
              developers using potentially unsafe data in your code. This
              applies to any potentially unsafe input, not just GET or POST
              data - files, cookies, and HTTP headers, among other input
              sources, will all be run through the validation system, and the
              single point of access to such data guarantees that you really
              only process data you have validated.</member>
            </simplelist></para>

          <para><simplelist>
              <member><emphasis role="bold">It takes the pain out of HTML
              forms.</emphasis> Agavi features a very clever approach to
              handling forms for you that does not rely on helpers or a
              specific template language to work. Not only will it re-populate
              the information the user entered when a form is shown again
              after submission, it also assigns classes to erroneous fields
              and their labels, and can even insert error messages into your
              form without any placeholders in the markup. Of course, you have
              full control over all aspects at any time, allowing you to
              pre-populate forms with information from your database or other
              sources.</member>
            </simplelist></para>

          <para><simplelist>
              <member><emphasis role="bold">It offers powerful features for
              globalization.</emphasis> Besides support for translating
              strings in different languages, Agavi comes with the ability to
              format and parse numbers, dates and currencies in over 250
              different locales. It is aware of time zones, has extensive
              support for calendars and calendar operations, can give you a
              list of country names in the language (and script!) you like,
              and much, much more.</member>
            </simplelist></para>

          <para></para>
        </section>

        <section id="encourage-clean-pragmatic-design">
          <title>Encourage Clean, Pragmatic Design</title>

          <para>Agavi's whole structure helps you a lot with designing and
          structuring your applications so that you get things right from the
          beginning. It encourages loose coupling, making it easy to hide
          implementational details from the parts of your code that should not
          have to worry about the "inner workings" of things, which also means
          that your code becomes very forward-compatible: whether you just
          want to modify the way your code talks to the database, or add a web
          service interface to your existing application, you will notice that
          your project already is structured in such a way that you do not
          have to go back and change existing things to make it happen.</para>

          <para>Also, you'll be presented with certain best practices from the
          beginning, as Agavi's project skeletons are structured to help you
          avoid mistakes in the critical early phase of development where you
          build the foundation for your software. This ensures that you can
          fully benefit from all the features that made you choose Agavi in
          the first place.</para>

          <para>And because Agavi follows the Model-View-Dispatcher (MVC)
          architecture, your code automatically becomes highly efficient as
          the various parts are cleanly separated, making your application
          easily maintainable:</para>

          <para><simplelist>
              <member>The <emphasis role="bold">Model</emphasis> accesses your
              data. It might talk to a database, or to a web service, or use
              smoke signals to acquire the information it returns to you; the
              essential point is that the way the data is retrieved is
              absolutely irrelevant to the code that uses the model. So in the
              beginning, your application would use models that return "fake"
              dummy test data for rapid prototyping, and later, you will write
              the actual code that talks to a database.</member>
            </simplelist></para>

          <para><simplelist>
              <member>The <emphasis role="bold">View</emphasis> presents your
              data. For Web sites, that typically means it renders an HTML
              document from one or more templates. But it could also build an
              RSS feed from the data it was given, or create a JSON data
              structure for the Ajax functionality of your application - it's
              all up to you!</member>
            </simplelist></para>

          <para><simplelist>
              <member>The <emphasis role="bold">Dispatcher</emphasis> contains
              the business logic: the code that talks to the model, transforms
              the data, performs necessary tasks and then prepares data for
              the View. In Agavi, we call this the
              <firstterm>Controller</firstterm>. After it has finished its task,
              it tells the system which View to use to generate the
              output.</member>
            </simplelist></para>
        </section>
      </section>

      <section id="what-a-framework-shouldnt-do">
        <title>What a Framework Shouldn't Do</title>

        <section id="lock-you-in">
          <title>Lock You In</title>

          <para>This is the most important point about a framework. It should
          not lock you into a certain way of building your HTML output, or the
          way you deal with your database.</para>

          <para><important>
              <para>Of course, this is a bit of a moot point. You might argue
              that by using a framework in the first place, you're locking
              yourself in already - and you'd be right to insist! There is no
              doubt that by choosing a framework, you have to stick to it -
              not forever, of course, but you cannot simply cut and paste your
              code to port a project to a different framework. If a framework
              promises you that, they're either lying, or they don't deserve
              the label "framework" because their implementations are so
              low-level they provide only a simple toolkit (or, as they're
              called these days, a component library).</para>
            </important>A framework can lock you in in many ways, like:</para>

          <para><simplelist>
              <member>Require you to use some object relational mapper tool to
              leverage the full potential of the framework. Many frameworks
              out there do this, and some people like that, while others
              don't. A good example is the infamous Ruby on Rails - a lot of
              it's glamour is due to it being strongly tied to the
              ActiveRecord ORM layer, and if you wish to use something else,
              some of the "Rails feeling" gets lost.</member>
            </simplelist></para>

          <para><simplelist>
              <member>Force you to use a certain template language in order to
              be able to use all features. Many, many, many frameworks come
              with helpers for everything you could possibly imagine, from
              creating an opening <code>&lt;form&gt;</code> tag to inserting
              stylesheets or even javascript effects. If you try to use the
              template language of your choice, you have to replicate all this
              stuff if you want to use it. And what's more, all these helpers
              often do only 95% of what you want them to do, but not quite the
              thing you had in mind. (Besides the obvious fact, of course,
              that you might just outright hate the template language the
              framework authors think is best for everyone, and that can ruin
              the whole experience.)</member>
            </simplelist></para>

          <para>As you have probably guessed by now, Agavi tries hard not to
          lock you in to any of the above. You can use the template language
          you like, and everything just works - particularly the entire form
          handling system that was deliberately built in such a way that it is
          fully independent of any template language implementation.</para>

          <para>And while Agavi offers integration for database object layers
          like Propel, you do not have to use such a layer. If you like, you
          may use AdoDB for database access, or the now common PDO, or even
          vanilla pgsql_* functions - it's all up to you. And if there is no
          adapter for your favorite layer bundled in the source distribution,
          chances are that someone has written one and shared it somewhere.
          And if not, (e.g., if it's your home-made database wrapper you have
          learned to love over the years), you can easily write a custom
          driver for it (and even that is not necessary, but of course highly
          recommended).</para>
        </section>

        <section id="do-everything-to-please-people">
          <title>Do Everything To Please People, No Matter How Stupid It
          Is</title>

          <para>Sometimes, it's necessary to say "no." Many projects, over
          time, develop what's commonly known as "feature creep" or
          "featuritis". There are many things in the area of frameworks where
          you ask a thousand people for their opinion, just to get a thousand
          (or, in the worst case, even more) different answers. Not only must
          a framework decide not to implement a thousand different approaches
          in such a case, it's also very important to balance out precisely
          how much of a specific feature the framework should implement, or if
          it's better to leave it entirely up to the users.</para>

          <para>A good example of this is any feature that is not within the
          scope of a framework, or that can work perfectly fine without being
          tied to the framework. A common feature is the ability to send
          e-mail. Smart frameworks don't have such a feature, because there
          already are many, many different libraries to choose from, many of
          which have matured over the course of years and as such are very
          stable and comfortable to use. There is simply no reason why a
          framework should be able to send e-mail, rotate image files, or come
          with a pre-made shopping cart module. Besides locking people in,
          every new feature that others solve better means increased activity
          on the support channels, derogating the quality of support for all
          users.</para>
        </section>

        <section id="making-you-forget-what-programming-is-about">
          <title>Making You Forget What Programming Is About</title>

          <para>Many frameworks have so many helpers for so many things that
          do stuff in certain ways that people might easily become totally
          immersed in them. Users start to neglect what programming is really
          about: using one's own imagination and ingenuity. A framework should
          fuel the human thirst for knowledge and excellence, and not bury it
          under a pile of stuff targeted mainly at people who are too lazy to
          learn how things work - and learning how things work is an important
          factor in enabling people to leverage a tool's full potential.
          That's why this manual will, from time to time, delve into
          explaining the inner workings of Agavi, in case you're
          interested.</para>
        </section>
      </section>
    </section>

    <section id="history">
      <title>A Brief Look at Agavi's History</title>

      <para>The Agavi project was started in early 2005 as a fork of the then
      well-known Mojavi framework for PHP. Mojavi had gathered a pretty large
      community over the years, but the new version 3 didn't see overly active
      development and was, despite the open source license, not developed in a
      typically open source manner, i.e. with active involvement of and
      feedback from the community, or access to the main development
      repository, issue tracker and so on.</para>

      <para>As a result, a couple of guys from Keller, Texas (namely Mike
      Vincent and Bob Zoller) forked Mojavi and labeled it Agavi (after the
      Agave plant which grows in the Mojave desert), with the main goal of
      creating a community-driven project with an open and transparent
      development process. A message with the fork announcement was posted on
      the Internet and in the Mojavi forums, and Agavi quickly gathered a
      small but loyal user base and more contributors.</para>

      <para>The first version released to the public was 0.9.0, and as the
      version number implies, it was believed that a final 1.0 release could
      follow soon after that. It turned out, however, that there were other
      unresolved issues that had to be addressed, and so it wasn't until the
      end of 2005 that a new 0.10.0 version was released to the public.</para>

      <para>While Agavi never had any official structure to its development
      team initially, the founders had less and less free time to spend on the
      project, and Bob ultimately made David Zülke "captain of the ship" as he
      put it in early 2006, and the decision was made to adjust the roadmap a
      bit, putting important features such as a routing and
      internationalization on the schedule for 1.0, since other frameworks,
      mostly inspired by Ruby on Rails, had begun to offer such functionality.
      A 0.11 release before a final 1.0 was planned in order to be able to
      make any changes, should they be necessary, before releasing a final 1.0
      version to the general public.</para>

      <para>In the end, 0.11 implemented a great many more features than
      originally planned, and as time went on, many of the core aspects of the
      framework, which was still heavily based on Mojavi 3, were changed
      drastically (so much in fact that at the time of this writing, many
      parts of Agavi do not resemble Mojavi much anymore). A lot of this work
      was necessary to prepare Agavi for the challenges frameworks face today
      and in the future; a solid, structured foundation is very important in
      order to be able to adapt to new developments and grow without having to
      introduce hacks or workarounds that would otherwise be necessary to
      introduce new functionality without breaking backwards
      compatibility.</para>

      <para>Agavi 0.11 is what you see today. Soon after work on 0.11
      commenced, it was decided that version 1.0 should be pretty much
      identical in terms of features, but with comprehensive documentation and
      everything a community would need after the launch. This "pre-1.0
      release" was deliberately flown "below radar" in order to keep Agavi
      from getting wide public attention before the documentation was fully up
      to scale with the framework itself - everything else would have scared
      off a lot of people very quickly and thus possibly ruined the chances of
      ever getting a large user base.</para>
    </section>
  </chapter>

  <chapter id="getting-started">
    <title>Getting Started</title>

    <section id="prerequisites">
      <title>Prerequisites</title>

      <para>Agavi's minimum requirement is PHP version 5.1.3 or newer. DOM,
      Reflection and SPL extensions are required, but these are always enabled
      by default, unless you're using one of these weird Linux distros made by
      "smart" people who think they know better.</para>

      <para><note>
          <para>It should be pointed out that Agavi is not a framework for
          beginners. To leverage the functionality and the advantages of it's
          structure and philosophy, a good knowledge of PHP is required, and
          it's highly recommended that you are familiar with concepts such as
          MVC, and (web) application development in general.</para>
        </note>Also, you usually need a web server, such as Apache, unless you
      only want to write a console application. Agavi should work fine with
      all web servers that support PHP. Apache versions 1 and 2, LightTPD and
      Microsoft Internet Information Server have been tested and verified to
      be compatible with the framework and it's components, such as the
      routing.</para>

      <para>If you want to install Agavi via PEAR, you do, obviously, need
      PEAR installed. If you'd like to grab it straight from the SVN
      repository, you'll need a Subversion client installed, of course. Either
      way, we recommend you have Phing installed, because creating a project,
      controllers, view and all these things by hand becomes utterly annoying over
      time, and the command line utility uses Phing to relieve you of that
      burden.</para>
    </section>

    <section id="installation">
      <title>Installation</title>

      <section id="installation-pear">
        <title>PEAR</title>

        <para>Agavi uses a PEAR Channel for release distribution. In order to
        be able to install releases via PEAR, you have to discover the Agavi
        PEAR Channel first:</para>

        <para><command>pear channel-discover pear.agavi.org</command></para>

        <para>Now you're ready to install Agavi:</para>

        <para><command>pear install agavi/agavi</command></para>

        <para>You now probably see an error message telling you that PEAR was
        unable to install Phing. Agavi needs Phing, and tries to install it,
        but this will fail if it doesn't know Phing's Channel Server yet.
        Since discovering channels gets massively annoying over time, you can
        tell PEAR to automatically add channels as it comes across
        them:</para>

        <para><command>pear config-set auto_discover 1</command></para>

        <para>If you want to install all dependencies (i.e. including Creole
        and Propel), type:</para>

        <para><command>pear install --alldeps agavi/agavi</command></para>

        <para>If you're still having trouble installing things, you might have
        to change your preferred state setting in PEAR:</para>

        <para><command>pear config-set preferred_state beta</command></para>

        <para>Also, it is possible to obtain a specific version of
        Agavi:</para>

        <para><command>pear install agavi/agavi-0.11.0</command></para>

        <para><tip>
            <para>Depending on your system configuration, you might need to
            run these commands with superuser rights. This is, for instance,
            often the case with PEAR installs on Mac OS X. You can simply
            prepend <command>sudo</command> to each command to run it with the
            appropriate permissions.</para>
          </tip></para>
      </section>

      <section id="c1-installation-by_hand">
        <title id="c1-installation-by_hand-title">By Hand</title>

        <para>Installing Agavi by hand is the logical choice if you can't use
        PEAR, or if you want to bundle Agavi with your application. Go to the
        <emphasis>Downloads</emphasis> section on the <ulink
        url="http://www.agavi.org">Agavi website</ulink> to get a release.
        After unpacking the archive, you can put the <filename>src</filename>
        folder into a folder of your choice and adjust your include path
        accordingly. Don't forget to copy <filename>etc/agavi-dist</filename>
        or <filename>etc/agavi.bat-dist</filename> script to an
        <filename>agavi</filename> or <filename>agavi.bat</filename>
        executable into a convenient location so you can use the shell
        commands for creating projects, modules, controllers etc. Keep in mind
        that you must edit the script and enter the path to your Agavi
        installation (that's the <filename>src</filename> folder you copied
        earlier) so everything works as intended.</para>

        <para>The more usual case, however, will be that you're shipping Agavi
        together with your application, either because you can't use Phing to
        install Agavi in the production environment, or because you want total
        control over what version of Agavi is used. In this case, copy the
        <filename>src</filename> folder to somewhere inside your application's
        directory structure (we recommend a <filename>libs</filename> folder
        that holds all libraries your app uses and that sits on the same level
        as the <filename>app</filename> and <filename>pub</filename>
        directories) and give it a different name, <filename>agavi</filename>
        would stand to reason. For that little extra something, copy the
        agavi-dist or agavi.bat-dist script again, maybe to your application
        root. Your <filename>pub/index.php</filename> can then be changed to
        use a relative path for including <filename>agavi.php</filename>, in
        our case that'd be <filename>../libs/agavi/agavi.php</filename>. Agavi
        will auto-determine and remember the path where it was loaded from,
        and works without any changes to your environment's include
        path.</para>
      </section>

      <section id="installation-svn">
        <title>From SVN</title>

        <para>Public access to the Subversion repository is possible via
        <ulink url="http://svn.agavi.org/agavi">http://svn.agavi.org/</ulink>.
        If you want to get the bleeding edge version, use
        <filename>/trunk</filename>. Specific releases are available through
        <filename>/agavi/tags</filename>. Also, you can get development
        versions of version branches (if applicable) via
        <filename>/agavi/branches</filename>.</para>

        <para><note>
            <para>Note that <filename>trunk</filename> might not always give
            you the latest version of Agavi. For example, once 0.11 RC1 was
            released, development moved over to
            <filename>branches/0.11</filename>, and trunk was not maintained
            until the final 0.11 release, when work on 1.0 started in
            trunk.</para>
          </note></para>

        <para>You can either perform an <command>svn checkout</command>, which
        creates <filename>.svn</filename> folders that allow you to stay up to
        date on changes in the repository via <command>svn update</command>,
        or you can simply <command>svn export</command> the contents of the
        repository without Subversion control folders, which is a good idea
        for example when you want to export a specific release into your own
        versioning control system.</para>

        <para>Once you have obtained a copy from the repository, you can
        either follow the instructions in <xref
        endterm="c1-installation-by_hand-title"
        linkend="c1-installation-by_hand" />, or you package a PEAR release
        yourself for local installation by first running</para>

        <para><command>pear channel-discover pear.agavi.org</command></para>

        <para><command>phing package-pear</command></para>

        <para>on the root directory of your checkout, followed by a</para>

        <para><command>pear package</command></para>

        <para>inside the <filename>build</filename> directory created by the
        first command. This will write a <filename>.tgz</filename> file which
        can be installed using PEAR. If you already have Agavi installed it
        might be a good idea to remove it by running <command>pear uninstall
        agavi/agavi</command>.</para>
      </section>

      <section id="installation-apache">
        <title>Apache Web Server Configuration</title>

        <para>Agavi doesn't require any changes to your Apache
        configuration.</para>

        <para>If you want to use the Routing without an
        <filename>index.php</filename> part in the URL path, you need
        mod_rewrite enabled, along with the respective AllowOverride options
        set. Refer to the "Removing the "index.php" Part From URLs" section in
        the Cookbook for further instructions.</para>
      </section>

      <section id="installation-lighttp">
        <title>LightTPD Configuration</title>

        <para>Agavi doesn't require any changes to your Lighty
        configuration.</para>

        <para>If you want to use the Routing without an
        <filename>index.php</filename> part in the URL path, you need the
        rewrite module enabled. Refer to the "Removing the "index.php" Part
        From URLs" section in the Cookbook for further instructions.</para>

        <tip>
          <para>You may run into issues when using aliases via
          <code>alias.url</code>. If routes are generated wrong or you see
          other error messages, disable(!) the
          <code>broken-scriptfilename</code> directive.</para>
        </tip>
      </section>

      <section id="installation-iss">
        <title>Microsoft IIS Configuration</title>

        <para>Agavi doesn't require any changes to your IIS
        configuration.</para>

        <para>If you want to use the Routing, you'll have to disable a feature
        of IIS that checks if a file exists before trying to execute it. To do
        that, follow these steps:</para>

        <para><orderedlist>
            <listitem>
              <para>Go to <guimenuitem>Control Panel</guimenuitem> -&gt;
              <guimenuitem>Administrative Tools</guimenuitem> -&gt;
              <guimenuitem>Internet Information Services</guimenuitem></para>
            </listitem>

            <listitem>
              <para>Pick your Website entry from the list, right-click it, and
              select <guimenuitem>Properties</guimenuitem></para>
            </listitem>

            <listitem>
              <para>Choose the <guimenuitem>Home Directory</guimenuitem>
              tab</para>
            </listitem>

            <listitem>
              <para>Click the <guibutton>Configuration...</guibutton> button
              near the bottom right of the box</para>
            </listitem>

            <listitem>
              <para>Select the <filename>.php</filename> extension entry in
              the list and click the <guibutton>Edit</guibutton> button</para>
            </listitem>

            <listitem>
              <para>Disable the checkbox that controls the checking for file
              existance function in the bottom left</para>
            </listitem>
          </orderedlist>If you want to use the Routing without an index.php
        part in the URL path, you need a plugin for IIS that mimics
        mod_rewrite's behavior, such as <ulink
        url="http://www.isapirewrite.com/">ISAPI_Rewrite</ulink>. Refer to the
        "Removing the "index.php" Part From URLs" section in the Cookbook for
        further instructions.</para>
      </section>
    </section>

    <section id="sample-application">
      <title>The Sample Application</title>

      <para>Agavi comes with a (very simple) sample application. To make it
      work, all you have to do is adjust
      <filename>samples/pub/index.php</filename> to point to
      <filename>agavi.php</filename>, whereever it's installed, and maybe
      change permissions of <filename>samples/app/cache</filename> so it's
      writeable by your web server or PHP. Then, fire it up in your browser
      and play around with it.</para>

      <para>While not overly complex, the sample application's code should
      give you a basic understanding of what a software project in Agavi would
      look like in terms of structure.</para>

      <para>The sample app also supports XMLRPC. It exposes a method called
      "getItemPrice" that can be used to retrieve the price for the products
      the SearchEngineSpam controller knows. Use the following script to test this
      (needs curl and xmlrpc extensions):</para>

      <para><programlisting>&lt;?php

header('Content-Type: text/html; charset=utf-8');

?&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;test&lt;/title&gt;
    &lt;meta http-equiv="Content-Type" value="text/html; charset=utf-8" /&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;pre&gt;
&lt;?php
$request = xmlrpc_encode_request('getItemPrice', array('name' =&gt; 'viagra'), array("encoding" =&gt; "utf-8", "escaping" =&gt; "markup"));

$url = "http://localhost/path/to/the/samples/pub/xmlrpc.php";

$header[] = "Content-type: text/xml; charset=utf-8";
$header[] = "Content-length: ".strlen($request);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_HEADER, true);

$data = curl_exec($ch);
if(curl_errno($ch)) {
  echo curl_error($ch);
} else {
  curl_close($ch);
  echo htmlspecialchars($data);
}

?&gt;
    &lt;/pre&gt;
  &lt;/body&gt;
&lt;/html&gt;</programlisting></para>
    </section>

    <section id="your-first-agavi-app">
      <title>Creating Your First Agavi Application</title>

      <para>Once you have everything set up, create a new directory for your
      application and, in there, run</para>

      <para><command>agavi project</command></para>

      <para>Follow the on-screen instructions. In case of doubt, confirm the
      default values given by the wizard.</para>

      <warning>
        <para>Agavi sets the permissions on
        <filename>yourproject/app/cache</filename> to "a+rwx", better known as
        "0777", which means the cache directory and all files in there will be
        read- and writeable by everyone. Remember that the compiled configs
        will, for example, still contain your database credentials in clear
        text. It might be a good idea to <command>chmod</command> the
        directory to the minimum required permissions so the folder is
        readable only by PHP or the Web Server. You have been warned.</para>
      </warning>

      <para>And that's it! You're done! Fire up your browser and point it to
      the <filename>pub</filename> directory of your application. You will see
      a nice welcome page that tells you everyting worked fine. This note will
      stay there until you remove the corresponding routing rule from
      <filename>app/config/routing.xml</filename>. While you're at it, you can
      also throw away the two <filename>.png</filename> files in pub/ that
      belong to the welcome page, and, of course, the
      <filename>WelcomeToAgaviController.class.php</filename>,
      <filename>WelcomeToAgaviSuccessView.class.php</filename> and
      <filename>WelcomeToAgaviSuccess.php</filename> template. You're now good
      to go and may add your own Controllers. But before that, reload your browser
      - a blank page appears! Time for the infamous "Hello, World" example -
      open up the default controller's template (remember, you entered the default
      controller's name during agavi project, but it usually is
      <filename>IndexSuccess.php</filename> in the default module's templates
      directory) and type some text. Back to the browser (you did remember to
      save, right?), reload, and there it is, the text you entered! Well done,
      that was the first step with Agavi, and the next ones will be just as
      exciting.</para>

      <para>If you want to add more Modules, Controllers or Models to your
      application, you can use the <command>agavi</command> script
      again:</para>

      <para><command>agavi module</command></para>

      <para><command>agavi controller</command></para>

      <para><command>agavi model</command></para>

      <para>The script uses code templates to generate all the files. You can
      use your custom code templates, too. Just put them whereever you like
      (look at <filename>src/buildtools</filename> to learn what templates
      there are and what the structure and file names look like). Then, create
      a new file called <filename>build.properties</filename> and add one line
      to it:</para>

      <para><programlisting>templates.dir = /my/project/path/mycodetemplates</programlisting>Of
      course, you don't have to provide custom versions of
      <emphasis>all</emphasis> code templates. Agavi will fall back to the
      bundled templates if it couldn't find a specific one in the path you
      specified.</para>

      <tip>
        <para>You will often want the code templates dir to sit inside your
        project directory. In order to avoid an absolute path in the setting,
        you can use <code>${project.dir}</code> to refer to your project
        directory.</para>
      </tip>

      <para>Also, you can have per-module code templates. Add a
      <filename>modules</filename> directory to your code templates folder,
      and then add a new folder with the same name as the module. Now you can
      add a code template in there, and it will only be used when generating
      something for that specific module.</para>

      <para>In addition to the templates directory, you can specify the
      extension used for the page template files (like
      <filename>IndexSuccess.php</filename>). The default extension is
      <filename>.php</filename>. The extension is applied both to the code
      template file name and to the name of the template that is written.
      Example:</para>

      <para><programlisting>template.extension = .tpl</programlisting>If you
      create a controller called "Index" and a view called "Success", the command
      line script will copy <filename>Template.tpl.tmpl</filename> to
      <filename>IndexSuccess.tpl</filename> for you.</para>

      <para>In case you're migrating from an Agavi 0.10 project where the app
      dir name is still <filename>webapp</filename>, or you simply don't want
      that directory in your project to be called <filename>app</filename>,
      you can customize this, too:</para>

      <para><programlisting>app.dirname = webapp</programlisting></para>
    </section>
  </chapter>

  <chapter id="agavi-basics">
    <title>Agavi Basics</title>

    <section id="system-architecture">
      <title>System Architecture</title>

      <para></para>
    </section>

    <section id="elements-of-an-application">
      <title>Elements of an Application</title>

      <para>modules</para>

      <para>controllers</para>

      <para>views and templates</para>

      <para>models and global models</para>

      <para>config files</para>
    </section>

    <section id="environments-and-contexts">
      <title>Environments and Contexts</title>

      <para>The framework is started by bootstrapping an environment. Typical
      environments would be "development", "testing" or "production". You may
      configure any number of environments, but only one of them is used
      during execution.</para>

      <para>Environments allow for extremely fine-grained settings for each
      machine an application is running on. The various Environments may have
      different database configurations, logging settings and levels, debug
      settings and even filters or factories. Also, each developer in a team
      may have his own Environment for development, with his or her own
      database settings etc. which eliminates the need for people constantly
      having to change their settings, accidentally committing changed files
      to SCM repositories or missing changes because configuration files were
      set to <emphasis>ignore</emphasis>.</para>

      <para>A Context encapsulates a running instance of the framework. While
      any aspect of the framework, even system settings and autoloads may be
      configured per Environment, you're a bit more restricted in Context
      configuration, and that's intentional. A Context's job is to hold the
      proper implementations that are needed to execute the application in the
      current <emphasis>context</emphasis> (therefore the name), such as "web"
      for normal requests to an application through a browser, "xmlrpc" for an
      XMLRPC interface of an application, or "console" for a Context that
      exposes the application to the command line.</para>

      <para>All configuration files support the configuration per Environment
      and Context (if applicable) without any performance disadvantage - Agavi
      compiles them into highly optimized variants for each Environment and
      Context when needed for minimum overhead.</para>

      <section id="closer-look-at-context-initialization">
        <title>A Closer Look at Context Initialization</title>

        <para>***TODO: needs to be re-written or removed. We have startup
        methods now.</para>

        <para>Agavi's context class (AgaviContext) is initialized according to
        settings defined in <filename>factories.xml</filename>. Normally you
        don't have to worry about how it is done but if you decide to
        specialize some of the Agavi's core classes the order of
        initialization might become important.</para>

        <para>Agavi's core classes are initialized in the following order by
        default:<orderedlist>
            <listitem>
              <para>DatabaseManager</para>
            </listitem>

            <listitem>
              <para>LoggerManager</para>
            </listitem>

            <listitem>
              <para>TranslationManager</para>
            </listitem>

            <listitem>
              <para>Storage</para>
            </listitem>

            <listitem>
              <para>Dispatcher</para>
            </listitem>

            <listitem>
              <para>Request</para>
            </listitem>

            <listitem>
              <para>User</para>
            </listitem>

            <listitem>
              <para>Routing</para>
            </listitem>
          </orderedlist>The initialization order of these framework core
        classes is defined in <classname>AgaviFactoryConfigHandler</classname>
        and it cannot be changed (unless you overwrite this configuration
        handler, of course).</para>
      </section>
    </section>

    <section id="how-a-request-is-processed">
      <title>How a Request is Processed</title>

      <para>If you call an URL that is handled by pub/index.php, Agavi will
      bootstrap the specified (or default) Environment and then create an
      instance of the specified (or default) Context (this instantiation sets
      up all of the core components of the framework). Finally, the request is
      dispatched from the Context's Dispatcher instance.</para>

      <para>The dispatch method first executes the routing (if enabled) to
      determine the Module/Controller that are to be executed. The routing returns
      an Execution Container for the first controller. Then, a filter chain
      containing all Global Filters is created, and the DispatchFilter is
      added to that chain as the last element. Each filter will be called in
      nested sequence, with the last filter being the DispatchFilter, which
      executes the first Execution Container with the requested Controller. After
      that, the control passes back through the filters to the dispatch
      method, which sends the Response contents and exits. Filters are given
      the global Response as a parameter to work with, so they can modify
      content, send Cookies and so on.</para>

      <para>When an Execution Container is run, Agavi does some checks to
      determine if the requested Module/Controller exists, if the Module the
      Controller belongs to is enabled and so on. Then, a filter chain is created,
      with the first filter being the Security Filter if security is enabled.
      This filter will forward unauthenticated users to the default "Login
      Controller" if a requested Controller requires authentication, and also prevent
      access of Controllers an user doesn't have sufficient credentials for by
      forwarding to the default "Secure Controller". After that, the Controller
      Filters are added to the chain, followed by the Controller Filters defined
      by the Controller's Module. The last filter in the chain is the Execution
      Filter. Again, each filter in the chain is called and may do
      modifications to the Response instance, which is a new one for each
      Controller that is processed and will be merged to the global Response by
      the Dispatcher once control returns to the forward method.</para>

      <para>The Execution Filter, once reached, will handle Validation, run
      the Controller (or skip execution if the Controller doesn't serve the Request
      method), determine the View to execute and then execute the View and,
      after that, start the rendering of the output.</para>
    </section>

    <section id="configuration">
      <title>Configuration</title>

      <section id="configuration-basic-concepts">
        <title>Basic Configuration Concepts</title>

        <para>Agavi's standard configuration file format is XML, but you can
        use any format you like for your custom files (you'll probably have to
        write a parser, though). Each configuration file may also have a
        parent, which is also read during compilation, and the two files get
        merged together, with the child file overwriting settings from the
        parent. Of course, the parent file may again reference a parent and so
        on, which is an excellent way to easily enforce common settings etc
        across projects.</para>

        <para>All configuration files are compiled into a very efficient
        format by their Configuration Handler to maximize performance. Once
        this compilation has occured, the compiled version will be used until
        the configuration file is modified. Then, the compilation will occur
        again. If Agavi is running in debug mode, configuration files are
        always re-compiled on each request.</para>
      </section>

      <section id="configuration-general">
        <title>General Format and Environment-/Context-Specific Blocks</title>

        <para>Each configuration file should have an XML prolog. The default
        encoding is UTF-8, but you can set any encoding you like; Agavi will
        then translate encodings during compilation. Note that this requires
        the iconv extension, unless you're using ISO-8859-1, which can be
        handled without the help of iconv.</para>

        <para>The root element of each configuration file is
        <code>&lt;configurations&gt;</code>. It may have an optional attribute
        called "parent" which can be used to specify the parent configuration
        file. This root element must contain at least one
        <code>&lt;configuration&gt;</code> element, which then contains the
        actual configuration directives.</para>

        <para>The reason why <code>&lt;configurations&gt;</code> contains
        <code>&lt;configuration&gt;</code> elements is that a
        <code>&lt;configuration&gt;</code> block can be specific to an
        environment, a context, or both. To achieve this, pass a space
        separated list of names to the "enviroment" and/or "context"
        attributes of the tag. This way, you can write very fine-grained
        config files to change behavior according to the situation. For
        example, the basic <filename>settings.xml</filename> file has
        different settings per environment (example simplified):</para>

        <para><programlisting>&lt;configurations&gt;
  &lt;configuration&gt;
    &lt;settings&gt;
      &lt;setting name="debug"&gt;false&lt;/setting&gt;
    &lt;/settings&gt;
  &lt;/configuration&gt;
  &lt;configuration environment="development"&gt;
    &lt;settings&gt;
      &lt;setting name="debug"&gt;true&lt;/setting&gt;
    &lt;/settings&gt;
  &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting>In this example, debug is always
        disabled unless the environment is set to "development". Note that
        environments and contexts do not have to be declared anywhere.
        Bootstrapping an environment or getting a context instance "activates"
        the environment or context. If you have declared settings specific to
        them, they'll be used. If not, the "global" settings (i.e. those in
        <code>&lt;configuration&gt;</code> blocks without further attributes)
        take effect.</para>

        <para>Environment-specific settings overwrite generic ones,
        context-specific settings overwrite environment-specific ones, and
        environment- and context-specific settings overwrite all of the
        before.</para>

        <para>You'll also soon notice that for each element that may occur
        multiple times, the parent element is the plural form of the name.
        <code>&lt;route&gt;</code> elements sit inside
        <code>&lt;routes&gt;</code>, <code>&lt;mouse&gt;</code> elements
        inside <code>&lt;mice&gt;</code> and so on.</para>

        <para><tip>
            <para>With the exception of the
            <code>&lt;configurations&gt;</code> element and all plural form
            nodes that have required attributes, you can also omit the plural
            containers. This makes deeply nested structures a lot more
            convenient to use, especially <xref
            endterm="configuration-parameter_blocks-title"
            linkend="configuration-parameter_blocks" />.</para>
          </tip>Also, you can use a <code>&lt;sandbox&gt;</code> element
        inside <code>&lt;configurations&gt;</code> to store XML chunks for
        easier inclusion in the local document using XInclude.</para>
      </section>

      <section id="configuration-parameter_blocks">
        <title id="configuration-parameter_blocks-title">Parameter
        Blocks</title>

        <para>Many tags in configuration files accept a
        <code>&lt;parameters&gt;</code> block as the child element which is
        usually used to specify initialization arguments to the respective
        resource. Each <code>&lt;parameter&gt;</code> inside the
        &lt;parameters&gt; container has a name, specified via the attribute
        "name", and a value. This value can, however, again be a
        <code>&lt;parameters&gt;</code> block. This inner block often does not
        need name attributes for the <code>&lt;parameter&gt;</code> elements,
        because it usually is simply a list of values for the parent
        <code>&lt;parameter&gt;</code>. Here's an example:</para>

        <para><programlisting>&lt;parameters&gt;
  &lt;parameter name="firstparam"&gt;a value goes here&lt;/parameter&gt;
  &lt;parameter name="secondparam"&gt;
    &lt;parameters&gt;
      &lt;parameter&gt;foo&lt;/parameter&gt;
      &lt;parameter&gt;bar&lt;/parameter&gt;
    &lt;/parameters&gt;
  &lt;/parameter&gt;
&lt;/parameters&gt;</programlisting></para>
      </section>

      <section id="configuration-substitution-and-directives">
        <title>Value Substitution and Configuration Directives</title>

        <para>Parameter blocks, but also many other attributes and values may
        contain the name of a configuration directive, wrapped in percent
        signs. <note>
            <para>The expansion of the configuration directive happens at
            compile time. This means that if you access a directive you set
            via <code>AgaviConfig::set()</code> before bootstrapping the value
            that was set when compiling the configuration file will be used
            throughout all requests.</para>
          </note>The following parameter will contain the path name of the
        project's app dir followed by "/fubar", because the directive is
        expanded before assignment:</para>

        <para><programlisting>&lt;parameter name="path"&gt;%core.app_dir%/fubar&lt;/parameter&gt;</programlisting>Also,
        in parameter blocks and sometimes in other locations, boolean
        expressions are expanded to actual boolean values:</para>

        <para><programlisting>&lt;parameter name="use_logging"&gt;false&lt;/parameter&gt;</programlisting>Will
        assign boolean false to the parameter "use_logging".</para>
      </section>
    </section>

    <section id="request-and-routing">
      <title>Request and Routing</title>

      <para>(Request and routing)</para>

      <section id="request">
        <title>Request</title>

        <para>request parameters and attributes, attribute namespaces, errors,
        cookies.</para>

        <section id="user-input">
          <title>User Input</title>

          <para>This chapter focuses on how to use user input in Agavi controllers
          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 controllers or views. Just remember that in real
          life you should never use any un-validated user input.</para>

          <para>All the input from the user like <code>$_GET</code> and
          <code>$_POST</code> arrays in the web context is stored into
          <classname>AgaviRequestDataholder</classname> (in the web context
          <classname>AgaviWebRequestDataHolder</classname> but you don't have
          to worry about the actual implementation) object that's given to the
          controller'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 <code>$_GET</code> and <code>$_POST</code> 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.</para>

          <programlisting>class Products_EditController extends WebShopBaseController
{
  // 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-&gt;getParameter('prdid');

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

    return 'Success';
  }</programlisting>

          <para>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 <methodname>getParameter(name,
          default)</methodname> of the
          <classname>AgaviRequestDataHolder</classname>.</para>

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

        <section id="passing-data-inside-the-system">
          <title>Passing Data Inside the System</title>

          <section id="passing-data-from-controller-to-view">
            <title>From Controller to View/Template</title>

            <para>{Controller::setAttribute, View::getAttribute, $template array /
            extracted vars}</para>

            <para>To pass data from the controller to the view or template, you
            would use the controller's <methodname>setAttribute</methodname>
            -method, which takes two parameters: a name-parameter identifying
            the data, and a mixed parameter of actual data. The data can be
            anything you can use as a variable in PHP itself, for instance
            strings, arrays or objects.</para>

            <para><programlisting>class Products_ViewController extends WebShopBaseController
{
  // route pattern /prouct/(id:\d+)
  // eg. www.example.com/product/123 to view the product with id 123
  public function executeRead(AgaviRequestDataHolder $rd)
  {
    $prdId = $rd-&gt;getParameter('prdid');

    $product = $this-&gt;getContext()-&gt;getModel('Product', 'Products', array('id' =&gt; $prdId));
    $this-&gt;setAttribute('product', $product);

    return 'Success';
  }

}</programlisting>Now the attribute "product" is available in the view as an
            attribute which you can access via the view's
            <methodname>getAttribute</methodname> -method, and in the template
            as a template variable. Attributes may also be set in separate
            namespaces, for more information see @@attribute
            namespaces@@.</para>

            <para>All the request parameter that the controller recieved are also
            available via the AgaviRequestDataHolder -object in the view. This
            is also true for the template, if the request data auto-assignment
            is enabled in <filename>output_types.xml</filename>.</para>

            <para>There are several variables automatically assigned in the
            template if set up in <filename>output_types.xml</filename>. These
            are the @@link:routing object@@, the request object (which is not
            the same as the <emphasis>request data</emphasis> object), the
            @@link:controller@@, the @@link:user@@ , the @@link:translation
            manager@@ and the request data -object. The variable name of these
            objects is naturally configurable to your own taste.</para>
          </section>

          <section id="passing-data-from-component-to-another">
            <title>From Component to Another</title>

            <para>Core messages (matched_routes,
            org.agavi.controller.forwards.*, fpf)</para>
          </section>
        </section>
      </section>

      <section id="routing">
        <title>Routing</title>

        <para>(routing functionality, getting info from the routing,
        generating urls)</para>

        <para>Normally when you do HTTP GET requests, parameters are specified
        using a format like index.php?param1=val1&amp;param2=val2. Routing can
        help you get rid of this ugly format that search engines do not
        particularly like and make the URI prettier for the users. Routing is
        basically a method to map URIs to module/controller -pairs and provide
        information for them, such as the parameters. Think of it as replacing
        mod_rewrite for Apache or ISAPI_Rewrite for Microsoft IIS but with a
        lot more power and features. Routes are defined in the file
        <filename>%core.app_dir%/config/routing.xml</filename></para>

        <para>Let's look at an example route:<programlisting>&lt;route name="viewproduct" pattern="^/products/(id:\d+)$" module="Shop" controller="ViewProduct" /&gt;</programlisting></para>

        <para>A request to the URL <uri>http://host.com/products/157</uri>
        would run the "ViewProduct" controller in module "Shop", with a request
        parameter <varname>id</varname> set to "157".</para>

        <para>Most of the "magic" is achieved using regular expressions
        (@linkto PCRE@). In the above example, the id parameter must consist
        of digits, otherwise, the pattern, and thus this whole route, would
        not match.</para>

        <note>
          <para>The <code>name:expression</code> syntax is really only a
          convenient form for named subpatterns, which look something like
          <code>(?P&lt;name&gt;pattern)</code></para>
        </note>

        <para>The example pattern is anchored at the beginning and end. This
        is very important, because if the pattern above wasn't anchored at the
        end, a URL like /products/157/YOUR-SITE-SUCKS etc would match, too. So
        you always have to pay attention to anchor patterns properly. There
        are cases when you don't want that to happen,</para>

        <para>Routes can run for either read- or write-requests. You tell a
        route which requests to be applied to by using the <code>method</code>
        -attribute. For read-methods, you would use
        <code>method="read"</code>, and for write-requests you would use
        <code>method="write"</code>. Routes are matched for both request
        methods by default, and are always matched in the order they are
        configured.</para>

        <para>It is worth to note that if the route has the module and controller
        attributes set, they will overwrite route parameters named "module"
        and "controller". If the attributes aren't set, you can use module and
        controller parameters, and they would do what you expect -- set the module
        and the controller of the request.</para>

        <section id="routing-optional-parts">
          <title>Optional Parts</title>

          <para>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?</para>

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

          <para><programlisting>&lt;route name="viewproduct" pattern="^/products(/{id:\d+})?$" module="Shop" controller="ViewProduct" /&gt;</programlisting>The
          difference between this route and the previous one is that now the
          slash and the id -parameters are optional. That is, the request
          <uri>http://host.com/products</uri> would also run the
          <methodname>Shop.ViewProduct</methodname> controller, but the
          id-parameter would be undefined. Your controller can then check if the
          id request parameter is null, and if so show a listing of, say, all
          products.</para>
        </section>

        <section id="routing-defaults">
          <title>Defaults</title>

          <para>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:</para>

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

          <para>indicates that if we do not specify a value for the
          lang-parameter (specified with the <code>for="lang"</code>
          -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".</para>
        </section>

        <section id="routing-pre-and-postfixes">
          <title>Pre- and Postfixes for Parameters</title>

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

          <para>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:</para>

          <para><programlisting>^/uri(/pre-part-{varname:regexp}-post-part)$</programlisting></para>

          <para>Let's look at a more complicated example from the Sample
          Application:</para>

          <para><programlisting>&lt;route name="search_engine_spam" pattern="^/products(/buy-cheap-{name:[\S\s]+}-at-agavi-dot-org)?/(id:\d+)" module="Default" controller="SearchEngineSpam"&gt;
  &lt;defaults&gt;
    &lt;default for="name"&gt;/buy-cheap-{chainsaws}-at-agavi-dot-org&lt;/default&gt;
  &lt;/defaults&gt;
&lt;/route&gt;</programlisting>This would match the request
          <uri>http://host.com/products/37</uri> and
          <uri>http://host.com/products/buy-cheap-whatever-at-agavi-dot-org/37</uri>.
          The inner part is optional, and for Search Engine Optimization (or,
          in this case, stupid spamming) only.</para>

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

          <para><tip>
              <para>Pre- and Postfixes may also be regular expressions
              themselves. You must, however, define static @@default values@@
              so these routes can be @@generated@@</para>
            </tip></para>
        </section>

        <section id="routing-ignores">
          <title>Ignores</title>

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

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

          <para>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.</para>
        </section>

        <section id="routing-callbacks">
          <title>Routing callbacks</title>

          <para>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.</para>

          <para><code>onMatched</code> 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.</para>

          <para><code>onNotMatched</code> 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.</para>

          <para><code>onGenerate</code> 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.</para>

          <para><note>
              <para>For in-depth information on how to write your custom
              routing callbacks, please see the @@cookbook@@</para>
            </note></para>
        </section>

        <section id="routing-subroutes">
          <title>Subroutes</title>

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

          <para>Subroutes are routes that are defined under other routes. Let
          us explain through an example:</para>

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

          <para>This would <emphasis role="bold">not</emphasis> run the controller
          Blog in the module Default for the request
          <uri>http://host.com/blog</uri>. 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 -controller, you would have to use the
          request <uri>http://host.com/blog/</uri> (note the slash), and to
          run the Blog.ShowArticle with the id and title -parameters set, you
          would have to use the request
          <uri>http://host.com/blog/151-Agavi_rocks</uri>. This way you only
          have to define "top level" routes for your main controllers, and you can
          use subroutes to define routes to controllers that are conceptually
          below the "top level" controllers, making parsing of the route much
          faster.</para>
        </section>

        <section id="routing-other-things-to-match">
          <title>Other Things to Match</title>

          <para>Routing can do more -- like match against other sources, or do
          things other than setting module and controller. An example:</para>

          <para>Because this is a <abbrev>MVC</abbrev>-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
          <code>output_type</code> -attribute for the route:</para>

          <programlisting>&lt;route name="rss" pattern="/rss$" output_type="rss" stop="false" cut="true" /&gt;</programlisting>

          <para>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.</para>

          <para>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:</para>

          <programlisting>&lt;route pattern="text/javascript" source="_SERVER[HTTP_ACCEPT]" output_type="json" stop="false" /&gt;</programlisting>

          <para>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, <varname>$_SERVER</varname>,
          that allows to access it's members directly.</para>

          <para><note>
              <para>There are other match sources available as well. Please
              refer to the cookbook for more information on matching against
              other sources and information on how to create your own
              sources.</para>
            </note></para>
        </section>

        <section id="routing-generating">
          <title>Generating routes</title>

          <para>To generate routes in templates or controllers, you use the
          <classname>AgaviRouting</classname>-class which returns the URI or
          route as a string. You must use the <code>name</code> -attribute for
          the routes in order for the
          <classname>AgaviRouting</classname>-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</para>

          <programlisting>$ro-&gt;gen(routename[, array parameters[, array options]])</programlisting>

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

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

          <para>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:</para>

          <para><programlisting>$ro-&gt;gen("blog.article", array('id' =&gt; 151, 'title' =&gt; 'Agavi_rocks'), array('relative' =&gt; false));</programlisting></para>

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

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

          <para><programlisting>$ro-&gt;gen(null, array(), array('fragment' =&gt; 'foobar'));</programlisting></para>
        </section>
      </section>
    </section>

    <section id="controllers-and-models">
      <title>Controllers and Models</title>

      <para>(what they do and contain (business logic at different
      levels))</para>

      <para>Before we talk about Controllers and Models in Agavi let's take a
      brief look at the MVC (Model-View-Dispatcher) paradigm. The idea behind
      MVC is that the view (a presentation layer, user interface) and the
      model (an object, or alike, that represents some information about your
      application domain) should be de-coupled in such a way that the model is
      totally independent of the view. In MVC this is achieved by putting a
      controller between these two (this is not entirely accurate and in any
      case a simplification but we don't go into that).</para>

      <para>When looking at Agavi's classes it's easy to see what's the view
      part and where's the controller. Models are of course your own classes
      although they can derive from an AgaviModel class. But where do Controllers
      stand in this scheme? Orthodoxly they are a piece of the controller (or,
      some could argue, the controller itself) but Agavi's Controllers can be seen
      as the glue between the model and the controller. The Dispatcher decides
      what Controller to trigger and after that it's up to the Controller to execute
      the proper domain logic. Some trivial domain logic can reside in the
      controller but to keep your application in accordance with MVC the actual
      model part of your design should be separated from the controller.</para>

      <note>
        <para>Understanding the idea and the value of MVC is essential in all
        software designing. For an in-depth rationalization of MVC paradigm
        you can consult Martin Fowler's Patterns of Enterprise Application
        Architecture (ISBN 0321127420).</para>
      </note>

      <section id="models">
        <title>Models</title>

        <para>As said before you write your own models for the application and
        Agavi doesn't really mind how you do it (some people like to make
        their models framework independent so that they can be used anywhere).
        There are, however, a few things to point out that can make it easier
        for you to use your models.</para>

        <para>Firstly you can ask Agavi to handle the loading and the
        initialization of a model. Agavi divides models into global models and
        module models. Global models go into <filename>app/models/</filename>
        and module models into
        <filename>app/modules/MyModule/models/</filename>. An instance of a
        model is retrieved using <methodname>getModel(string modelName [,
        string moduleName] [, array parameters])</methodname> of the
        <classname>AgaviContext</classname>. The first, and the only required,
        parameter of that method is the name of your model class. The second
        parameter is the name of the module where the model resides. Set/leave
        it to <code>null</code> to retrieve a global model. If given, the
        parameter array is passed to the initialization method of you model or
        to the constructor if <methodname>initialize(array)</methodname> is
        not defined.</para>

        <para>Secondly you can make singleton models simply by implementing
        <interfacename><classname>AgaviISingletonModel</classname></interfacename>.
        No other changes are needed to your model. Agavi stores the instances
        of your singleton models. To retrieve an instance, simply call
        <methodname>getModel()</methodname> on the
        <classname>AgaviContext</classname>.</para>

        <para>Examples:</para>

        <programlisting>/* Loads /app/modules/Dogs/models/Dog[Model].class.php and initializes it with a name and a breed. */
$myDog = $this-&gt;getContext()-&gt;getModel('Dog', 'Dogs', array('name'=&gt;'Nelli', 'breed'=&gt;'Novascotian retriever'));

/* class SinglesBar implements AgaviISingletonModel */
$bar1 = $this-&gt;getContext()-&gt;getModel('SinglesBar'); //loads and initializes the model.
$bar2 = $this-&gt;getContext()-&gt;getModel('SinglesBar'); //returns the same instance of SinglesBar as the line above.</programlisting>
      </section>

      <section id="controllers">
        <title>Controllers</title>

        <para>(controllers: execution, execution methods, serving request methods,
        default view name, validation, security)</para>

        <para>Like we noticed before, controllers can be seen as a part of the
        controller, or as glue between the controller and the model. The
        controller can execute controllers in two ways depending on the request
        method. In a web-context this could mean the controller would call the
        <methodname>executeRead</methodname> -method for a HTTP GET-request or
        <methodname>executeWrite</methodname> for a HTTP POST-request. Both
        methods take an <classname>AgaviRequestDataHolder</classname> -object
        as parameter. If the controller contains an
        <methodname>execute()</methodname>-method and neither
        <methodname>executeRead()</methodname> or
        <methodname>executeWrite()</methodname>, the controller will call the
        <methodname>execute()</methodname> method regardless of the request
        method. If the request method is POST but it does not implement the
        write method or similarly the request method is GET but the controller
        does not implement the read method, it can run a default view by
        implementing the <methodname>getDefaultViewName</methodname>
        -method.</para>

        <para>Before the controller executes the execute-method, it will check
        two things: does the controller require security (ie a user that has
        logged in) and what credentials, if any, the user must have to be
        allowed to execute the controller.</para>

        <para>The former is simply done by adding an
        <methodname>isSecure()</methodname> -method to the controller which
        returns true if security is required. Credential requirements are
        defined by implementing a <methodname>getCredentials()</methodname>
        -method which can return either a string indicating a simple
        credential, or an array of credentials.</para>

        <para>To require the credential "Edit", simply return "Edit" from
        <methodname>getCredentials()</methodname>. To require both "Edit" and
        "Write" -credential, return <code>array("Edit", "Write")</code>. To
        require EITHER the "Edit" OR the "Write" -credentials, you would
        return <code>array(array("Edit", "Write"))</code>, and to require the
        "Edit"-credential AND EITHER "Write" or "Foo" (or both), return
        <code>array("Edit", array("Write", "Foo"))</code>.</para>

        <para>After the controller has decided if the user is allowed to
        execute the controller, validation occurs. If the validation fails, the
        controller's <methodname>handleError()</methodname> will be run, which
        would, like the execute() return a string or an array indicating which
        view or controller/view -pair should be handed the control. The validation
        error messages are available for the templates using
        <methodname>$container-&gt;getValidationManager()-&gt;getErrorMessages()</methodname>
        which returns an array of messages. For more information on controller
        validation, see section 11 in this manual.</para>

        <para>When the controller has finished, it must tell the controller which
        view to execute. This of course depends on the outcome of the controller:
        if we are successful, we would want to pass the control over to a
        <classname>SuccessView</classname>, if we had some form of error, we
        would use <classname>ErrorView</classname> and if we need input from
        the user, we'd use <classname>InputView</classname>. The controller can
        return a string like "Success" to indicate the controller finished
        successfully, and the controller would use the
        <classname>ClassnameSuccessView</classname>, or it can return an array
        with two indices specifying the controller/view pair to hand the execution
        to.</para>
      </section>
    </section>

    <section id="views-renderers-templates">
      <title>Views, Renderers and Templates</title>

      <para>what they do and contain (only presentational stuff)</para>

      <para>views: execution, execution methods, where you set the output type
      (initialize at the latest)</para>

      <para>layouts: how to define, how to load</para>

      <para>layers: what they do, how they work</para>

      <para>slots: blah</para>

      <para>templates and renderers: engines, variable naming etc</para>
    </section>

    <section id="output-types-and-response">
      <title>Output Types and Response</title>

      <para>output types, what's the point of it, explain how easy it is to
      add a new one etc</para>

      <para>response: why they exist, whey they are isolated</para>
    </section>

    <section id="session-handling-and-security">
      <title>Session Handling and Security</title>

      <para>explain the storage, explain why you never use it directly</para>

      <para>explain the user, how it works, what you can do with it, how you
      do authentication, credentials etc</para>

      <section id="security-rbac">
        <title>Role-Based Access Control</title>

        <para>Role-Based Access Control (RBAC) is an approach to restricting
        system access to authorized users. To learn more about Role-Base
        Access Control (RBAC) in general you could start from <ulink
        url="http://en.wikipedia.org/wiki/Role-Based_Access_Control">http://en.wikipedia.org/wiki/Role-Based_Access_Control</ulink>.
        For an in-depth paper about Role-Base Access Control (RBAC) see
        National Institute of Standards and Technology's "Proposed NIST
        Standard for Role-Based Access Control" (a link to that paper can be
        found from the Wikipedia's page).</para>

        <para>Agavi has an easy-to-use RBAC user implementation
        <classname>AgaviRbacSecurityUser</classname>. It extends the features
        of <classname>AgaviSecurityUser</classname> to enable automatic
        assignment of credentials based on a role or roles granted to the
        user.</para>

        <section id="security-rbac-enabling">
          <title>Enabling RBAC</title>

          <para>The user implementation used by Agavi is configured in
          <filename>%core.app_dir%/config/factories.xml</filename>. To plug in
          the RBAC user you simply alter the user class to be used.</para>

          <programlisting>&lt;user class="AgaviRbacSecurityUser" /&gt;</programlisting>

          <para>Normally you would extend
          <classname>AgaviRbacSecurityUser</classname> and create your own
          user implementation with custom login and logout methods but for now
          we want to keep our set-up simple and use
          <classname>AgaviRbacSecurityUser</classname> directly.</para>
        </section>

        <section id="security-rbac-roles-and-credentials">
          <title>Defining Roles and Credentials</title>

          <para><classname>AgaviRbacSecurityUser</classname> reads the role
          and credential definitions from an XML-file located by default in
          <filename>%core.app_dir%/config/rbac_definitions.xml</filename>. If
          you want to keep them in some other file you can use a configuration
          parameter <parameter>definitions_file</parameter> in
          <filename>factories.xml</filename>.</para>

          <programlisting>&lt;user class="AgaviRbacSecurityUser"&gt;
 &lt;parameter name="definitions_file"&gt;%core.app_dir%/data/roles.xml&lt;/parameter&gt;
&lt;/user&gt;</programlisting>

          <para>Roles in the definition file are defined hierarchically from
          the bottom up so to speak. That means that a role can have an inner
          role (or many of them) that inherits all the credentials of the
          parent. This is a very common way to define roles in RBAC. Here is a
          simple exaple with three roles that are all in a straight line in
          the hierarchy ie. all photomoderators are photographers and all
          photographers are members and they inherit all the credentials from
          the parent. This is important to understand because now you don't
          need to grant the user all three roles separately but just the
          topmost.</para>

          <programlisting>&lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt;
&lt;configurations&gt;
  &lt;configuration&gt;
    &lt;roles&gt;
      &lt;role name="member"&gt;
        &lt;permissions&gt;
          &lt;permission&gt;photos.comments.add&lt;/permission&gt;
        &lt;/permissions&gt;
        &lt;roles&gt;
          &lt;role name="photographer"&gt;
            &lt;permissions&gt;
              &lt;permission&gt;photos.add&lt;/permission&gt;
            &lt;/permissions&gt;
            &lt;roles&gt;
              &lt;role name="photomoderator"&gt;
                &lt;permissions&gt;
                  &lt;permission&gt;photos.edit&lt;/permission&gt;
                  &lt;permission&gt;photos.delete&lt;/permission&gt;
                &lt;/permissions&gt;
              &lt;/role&gt;
            &lt;/roles&gt;
          &lt;/role&gt;
        &lt;/roles&gt;
      &lt;/role&gt;
    &lt;/roles&gt;
  &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting>

          <note>
            <para>For larger systems this is obviously not the perfect way to
            store the definitions but instead a database of some sort would be
            used. To load the definitions from some other source you only have
            to override <classname>AgaviRbacSecurityUser</classname>'s
            <methodname>loadDefinitions()</methodname> method</para>
          </note>
        </section>

        <section id="security-rbac-granting-roles">
          <title>Granting Roles to the User</title>

          <para>The roles have now been designed and defined in the XML-file
          and we have some database of the users and their roles. For
          simplicity's sake we don't bother ourselves with that database now
          but simply take it for granted that know the role(s) of the user
          after he has logged in.</para>

          <para>AgaviRbacSecurityUser has six methods for role managing:
          <methodname>grantRole(string)</methodname>,
          <methodname>grantRoles(array)</methodname>,
          <methodname>revokeRole(string)</methodname>,
          <methodname>revokeAllRoles()</methodname>,
          <methodname>hasRoles(string)</methodname> and
          <methodname>getRoles()</methodname>. The methods are
          self-explanatory.</para>

          <para>If you want to understand how
          <classname>AgaviRbacSecurityUser</classname> actually works the
          method <methodname>grantRole(string)</methodname> is worth looking
          into. What it actually does is quite simple; it reads the role
          definitions and gives the user each credential the given role has
          explicitly or implicitly from the parent roles. The credential
          management itself is actually part of
          <classname>AgaviSecurityUser</classname> and
          <classname>AgaviRbacSecurityUser</classname> only extends it with
          role-to-credential mapping. This is the beauty of the
          object-oriented design in controller.</para>
        </section>

        <section id="security-rbac-protect-controllers">
          <title>Protecting Your Controllers</title>

          <para>Protecting your controller is simply a matter of defining the
          credential needed to be able use the controller. This is done by
          overriding <classname>AgaviController</classname>'s
          <methodname>getCredentials()</methodname> method.</para>

          <programlisting>class Photos_AddController extends PhotoSystemBaseController
{
  public function getCredentials()
  {
    return 'photos.add';
  }</programlisting>

          <para>As the method name implies you can require more than one
          credential or even complex combinations of credentials (eg. 'a' OR
          'b' AND 'c') but this is explained in detail in another chapter (a
          link is going to be added later).</para>
        </section>
      </section>
    </section>

    <section id="validation">
      <title>Validation</title>

      <section id="validation-why">
        <title>Why Validation?</title>

        <para>It is strongly recommended to validate any request data. All
        request data including headers and cookies comes from the user and
        it's content is dictated by the the user. This user may as well be a
        malicious user trying to attack your application/server/database or
        use your application to attack other people visiting your website
        through XSS-attacks or similar. No input to your application which is
        not under your control should therefore be trusted.</para>

        <para>There are other reasons to validate data: Think of a newsletter
        application form - it's always a good thing to check whether the data
        the user entered is at least a syntactically correct email-address.
        Sometimes typing errors happen and the user is frustrated that he
        didn't get the newsletter he ordered. It would have been better to
        check the data the user entered and provide him with a friendly error
        message at the time of registration.</para>

        <para>The best situation you can be in is if you know exactly what
        input data is valid - e.g. if your page expects an id parameter to
        pull a record from the database you know for sure that it must
        absolutely be an integer and everything else is an attempt to trick
        your application to do something wrong. Other situations may not be as
        easy, but you should still try to validate as much data as
        possible.</para>
      </section>

      <section id="validation-when">
        <title>When does Validation happen</title>

        <para>Validation happens if the controller serves the incoming request
        method, that is if the controller declares an execute method that matches
        the request type (<methodname>executeRead()</methodname> for get
        request, <methodname>executeWrite()</methodname> for post request or a
        generic <methodname>execute()</methodname> method), immediatly before
        the controller is executed.</para>
      </section>

      <section id="validation-how">
        <title>How to validate</title>

        <para>The rules for the validation are defined in validators. A
        validator is an object that checks wether an input parameter conforms
        to a set of given constraints - such as "is the parameter 'id' really
        an integer value etc.". There two ways of registering a validator and
        a third way to perform more elaborate validations that cannot be
        handled by a validator:</para>

        <section id="validation-xml-config">
          <title>XML Configuration</title>

          <para>There are several ways of validating input data. The simplest
          way is placing an XML configuration file with the proper
          configuration in the "validate" directory of the module. The XML
          file must be named &lt;ControllerName&gt;.xml, that is if your controller is
          named "LoginController", the XML file must be "Login.xml". In this file,
          you can define which validators will be registered for any request
          handled by the controller. It is important to note that even though you
          can set some validators not to execute on a read or write request,
          those validators will be registered anyways and as you can't
          register a validator twice, you can only have one input parameter
          validated in a different manner on read and write by defining two
          different validators. Another way which provides finer control over
          what validators will be registered on read/write requests is the
          registerValidators() family of methods.</para>

          <section id="validation-xml-config-example">
            <title>Example XML Configuration (from the sample app,
            LoginController)</title>

            <programlisting>&lt;?xml version="1.0" encoding="UTF-8" standalone="no"?&gt;
&lt;configurations&gt;
  &lt;!-- custom validators and default parameters --&gt;
  &lt;configuration&gt;
    &lt;validators&gt;
      &lt;validator class="string" name="username_too_short"&gt;
        &lt;argument&gt;username&lt;/argument&gt;
        &lt;error&gt;The username you supplied is less than 4 characters&lt;/error&gt;
        &lt;parameter name="min"&gt;5&lt;/parameter&gt;
      &lt;/validator&gt;
    &lt;/validators&gt;
  &lt;/configuration&gt;
&lt;configurations&gt;</programlisting>

            <para>This registers a single validator that checks wether the
            username is longer than 5 characters. Let's look at this snippet
            in detail. The interestion block is the
            <code>&lt;validators&gt;</code> element. It contains a list of
            <code>&lt;validator</code>&gt; elements, each one representing a
            validator. A validator must have a type ("string" in this case,
            alternatively you can use the full class name). The name is
            optional and must be unique ("username_too_short" here) when
            supplied . Some validators can act upon multiple input parameters,
            each one wrapped in a <code>&lt;argument&gt;</code> tag. You can
            also validate array input parameters <link
            linkend="reference-validation-validating_arrays">using a special
            syntax.</link> You can define different <code>&lt;error&gt;</code>
            blocks for the various validation errors by supplying a name
            attribute, in this case there is only the generic error available.
            Finally, the <code>&lt;parameters&gt;</code> block lists the
            parameters that get passed into the validator. These depend on the
            type of validator you're trying to register. The
            AgaviStringValidator being used here for example accepts
            parameters such as minimum and maximum length etc.</para>
          </section>
        </section>

        <section id="validation-registervalidators">
          <title>registerValidators(), registerReadValidators(),
          registerWriteValidators()</title>

          <para>While the XML configuration method is convenient most of the
          time, sometimes a more fine grained control is nessesary. Sometimes
          you might wish to validate a parameter differently on a read request
          than on a write request or the validation might depend on data no
          known when you write the application. Think of a form that gets
          generated depending on some config parameters pulled from a
          database. When you write the controller, you don't know yet what form
          fields will be available and which type they have - however when the
          form gets displayed you will know. You just need to tell agavi about
          it - this is where the <methodname>registerValidators()</methodname>
          methods come into play. If your controller defines a method
          <methodname>registerReadValidators()</methodname>, it will be
          executed before <methodname>executeRead()</methodname> and all
          validators that you registered in this method will be executed as
          well. The same is true for
          <methodname>registerWriteValidators()</methodname>, only that it
          will be called before <methodname>executeWrite()</methodname> will
          run and <methodname>registerValidators()</methodname> will be
          executed before any of the execute methods will be run. That way,
          you can dynamically add validators, you can even mix both methods:
          use the XML for any validators that you you'll need for shure and
          use execute*Validators() to add anything that is dynamic. However,
          as noted above you can't register a validator twice.</para>

          <section id="validation-registervalidators-example">
            <title>Sample registerWriteValidators() (does the same as the XML
            above)</title>

            <para><programlisting>public function registerWriteValidators()
{
  $validationManager = $this-&gt;getContext()-&gt;getValidationManager();

  $arguments = array('username');
  $errors = array('' =&gt; 'The username you supplied is less than 4 characters.');
  $parameters = array (
    'name' =&gt; 'username_too_short',
    'min' =&gt; '5',
    'severity' =&gt; 'error',
    'method' =&gt; NULL,
    'required' =&gt; true,
    'class' =&gt; 'string'
  );

  $validator = new AgaviStringValidator();
  $validator-&gt;initialize($this-&gt;getContext(), $parameters, $arguments, $errors);
  $validationManager-&gt;addChild($validator);
}</programlisting>This example does the same as the XML style registration
            above.</para>
          </section>
        </section>

        <section id="validation-validate">
          <title>validate(), validateRead(), validateWrite()</title>

          <para>If a controller declares a method with the name
          <function>validate()</function>, it will get called after the
          registered validators have run but before the execute Method gets
          called. It recieves a single parameter, <code>$rd</code> with the
          type <classname>AgaviRequestDataHolder</classname>. If validate
          returns true, the execution continues, if it returns false,
          validation fails and the error must be handled. As with the
          register*Validator() family of methods, a method named
          <function>validateRead(AgaviRequestDataHolder $rd)</function> will
          only be called in read requests and a method named
          <function>validateWrite(AgaviRequestDataHolder $rd)</function> only
          on write request. You can use these methods for quick testing and to
          perform advanced validation that is not possible with validators.
          But, as validators are generic and reusable, you should look into
          creating your own validator whenever feasible.</para>

          <section id="validation-validate-example">
            <title>Sample validateWrite() (does the same as the XML
            above)</title>

            <programlisting>public function validateWrite(AgaviRequestDataHolder $rd)
{
  if (strlen($rd-&gt;getParameter('parent') &lt; 5) {
    $tm = $this-&gt;getContext()-&gt;getTranslationManager();
    $message = $tm-&gt;_('The username you supplied is less than 4 characters.', '.errors');
    $this-&gt;container-&gt;getValidationManager()-&gt;setError('username', $message);

    return false
  }
  return true;
}</programlisting>

            <para>This example does the same as the two earlier validator
            examples.</para>
          </section>
        </section>
      </section>

      <section id="validation-errors">
        <title>Handling Validation errors</title>

        <para>Once validation failed, the error must be handled. The default
        way is to render an error view, but sometimes you might wish to slip
        in some logic such as logging the error. You can do this by declaring
        a method named <function>handleError()</function> in your controller. You
        can also define different handlers for the request methods using
        handle*Error() (handleReadError, handleWriteError and so on). It will
        be called if a validation error occured and recieves a single
        parameter, <code>$rd</code> with the type
        <classname>AgaviRequestDataHolder</classname>. It must return the name
        of a view, just as the execute methods do.</para>
      </section>

      <section id="validation-fpf">
        <title>The FormPopulationFilter</title>

        <para>Once you validated the input data, there may be errors that must
        be returned to the client. The standard way is displaying the form
        back to the user and having him correct the errors in the input data.
        This can be done by pulling the supplied data from the request object
        in your form template and filling the input fields with the proper
        value. There is a more convenient way though: The
        FormPopulationFilter. It is a regular filter that gets executed
        everytime you post a form by default. It parses the resulting document
        and extracts the form element whose controller attribute matches the
        current page's URL. It then matches the input fields in this form
        against the request parameters and fills in the request values in the
        proper input fields. It even marks the input field and the
        corresponding label (if any) with a special CSS class that you can use
        to indicate an error to your users. While inserting the request
        parameters, it takes care of escaping the values properly so that XSS
        attacks are not possible.</para>
      </section>

      <section id="validation-other-things">
        <title>Other things Validators can do for you</title>

        <para></para>

        <section id="validation-normalization">
          <title>Normalization</title>

          <para></para>
        </section>

        <section id="validation-casting">
          <title>Casting Values (same as Normalization)</title>

          <para></para>
        </section>

        <section id="validation-i18n">
          <title>Validation and Internationalization</title>

          <para>If you have an internationalized application you need to
          translate the error messages as well. To make this possible, each
          validator accepts a "translation_domain" parameter. All error
          messages will be translated with the Translator registered for this
          domain.</para>
        </section>
      </section>

      <section id="validation-available-validators">
        <title>Available Validators</title>

        <para>Depending on the validator type, every validator accepts
        different parameters.</para>

        <section id="validation-stringvalidator">
          <title>String (AgaviStringValidator)</title>

          <para></para>
        </section>
      </section>

      <section id="validation-examples">
        <title>Examples</title>

        <programlisting></programlisting>
      </section>
    </section>

    <section id="filters">
      <title>Filters</title>

      <para>Each Filter calls the next one, making Filter Chains work like a
      <ulink url="http://en.wikipedia.org/wiki/Matryoshka_doll">Matryoshka
      Doll</ulink>.</para>
    </section>

    <section id="i18n">
      <title>Internationalization</title>

      <para>The i18n and l10n support in Agavi provides you with tools which
      help you to easily make your application available to different
      cultures. When internationalizing your application there are many things
      to take care of. The <ulink url="http://en.wikipedia.org/wiki/I18N">I18N
      page at Wikipedia</ulink> contains a list of what needs to be taken care
      about. Agavi provides you an easy to use solution to most<footnote>
          <para>Agavi currently helps you with the following
          items:<itemizedlist>
              <listitem>
                <para>Language translation (text strings, entire
                templates)</para>
              </listitem>

              <listitem>
                <para>Formatting date and time</para>
              </listitem>

              <listitem>
                <para>Formatting of numbers and currencies</para>
              </listitem>

              <listitem>
                <para>Time zone support</para>
              </listitem>

              <listitem>
                <para>Localized territory, country, language and currency
                names</para>
              </listitem>
            </itemizedlist></para>
        </footnote> of these points. Agavi can support these features because
      we are bundling the <ulink url="http://www.unicode.org/cldr/">Unicode
      Common Locale Data Repository</ulink> (CLDR) and the <ulink
      url="www.twinsun.com/tz/tz-link.htm">"Olson" timezone database</ulink>
      and making it available to applications. Agavi additionally includes a
      port of the calendar functionality from the <ulink
      url="http://icu.sourceforge.net">ICU project</ulink> which allows you to
      handle and calculate with date and time in millisecond precision from
      about 50000 BC to 50000 AD.</para>

      <para>To distinguish between the different settings for each culture
      Agavi uses the notion of locales. Each locale is uniquely defined by a
      locale identifier (as defined in the <ulink
      url="http://www.unicode.org/reports/tr35/#Identifiers">LDML
      definition</ulink>). You can only access these locales which are <link
      linkend="reference-translation-define_available_locales">defined as
      being available to your application</link>. Before using any of the
      <link linkend="reference-translation-translation_methods">translation
      related methods</link> of the
      <classname>AgaviTranslationManager</classname> you need to <link
      linkend="reference-translation-set_current_locale">specify the currently
      active locale</link> and at least one translation domain defining your
      message translator and optionally a different number/currency/date
      formatter or options to them. Currently Agavi only supports the
      definition of translation strings by using <ulink
      url="http://www.gnu.org/software/gettext/">gettext</ulink> as message
      translator (This doesn't use the gettext functionaly of PHP tho, but a
      custom parser for the .mo format used by gettext) but you can easily
      <link linkend="reference-translation-custom_message_translators">write
      your own custom message translators</link>.</para>

      <section id="i18n-domains">
        <title>translation domains?!</title>

        <para>Translation domains allow you to define different translators or
        different formats for the formatters. This allows you to define one
        domain which would read the translation messages from the database and
        another to read it from gettext. Or you can define different formats
        which you want to use when formatting or parsing dates.<note>
            <para>This should not be confused with gettexts text
            domains!</para>
          </note></para>
      </section>

      <section id="i18n-get-started">
        <title>Lets get started</title>

        <para>To use the translation you have to enable
        <code>use_translation</code> in your <filename>settings.xml</filename>
        and set up your translation.xml.<example>
            <title>translation.xml</title>

            <para><programlisting>&lt;configurations&gt;
 &lt;configuration&gt;
  &lt;available_locales default_locale="en_US" default_timezone="Europe/London"&gt;
   &lt;!-- English, United States --&gt;
   &lt;available_locale identifier="en_US" /&gt;
   &lt;!-- German, Germany and set the default currency to US Dollar --&gt;
   &lt;available_locale identifier="de_DE@currency=USD" /&gt;
  &lt;/available_locales&gt;

  &lt;translators default_domain="frontend"&gt;

   &lt;translator domain="frontend"&gt;
    &lt;message_translator class="AgaviGettextTranslator"&gt;
     &lt;!-- This would look for the gettext domain files in gettext compatible way --&gt;
     &lt;parameter name="text_domain_pattern"&gt;%core.app_dir%/locales/frontend/${locale}/LC_MESSAGES/${domain}.mo&lt;/parameter&gt;
    &lt;/message_translator&gt;
   &lt;/translator&gt;

   &lt;translator domain="backend"&gt;
    &lt;message_translator class="AgaviGettextTranslator"&gt;
     &lt;parameter name="text_domain_pattern"&gt;%core.app_dir%/locales/backend/${locale}/LC_MESSAGES/${domain}.mo&lt;/parameter&gt;
    &lt;/message_translator&gt;

    &lt;date_formatter&gt;
     &lt;parameter name="format"&gt;full&lt;/parameter&gt;
    &lt;/date_formatter&gt;
   &lt;/translator&gt;
  &lt;/translators&gt;
 &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting>That this example defines 2 locales as
            being available and "en_US" being the default locale should be
            obvious. The not so ovious part is the "@currency=USD": you can
            specify default options which will be used when the locale was
            requested and the option was not set when the locale was
            requested. You can also give parameters to the locales to set
            extended information which can be <emphasis>queried</emphasis>
            without loading the locale or <link
            linkend="reference-translation-overwrite_cldr_data">overwrite the
            cldr data</link> (not shown here).</para>

            <para>The slightly larger block of the file defines 2 translation
            domains: frontend (the default one) and backend. Both translators
            are using the gettext implementation. The parameters differ for
            each message translator implementation. To use the formatters with
            the default format of each locale you don't have to configure
            anything.</para>
          </example>When everything is configured you can start using the the
        _*() methods of the <classname>AgaviTranslationManager</classname>.
        For the examples assume <varname>$tm</varname> is the
        <classname>AgaviTranslationManager</classname> instance and
        <code>de_DE</code> the current locale.<example>
            <title>Translation message strings</title>

            <para><programlisting>$tm-&gt;_('Your Message');
#&gt; Deine Nachricht (default translation domain)

$tm-&gt;_('%s said: I am your father %s!', 'backend', null, array('Darth Vader', 'Luke'));
#&gt; Darth Vader sagte: Ich bin dein Vater Luke!

$tm-&gt;_('Your Message', null, 'en_US');
#&gt; Your Message

$tm-&gt;__('%d registered user', '%d registered users', 3, 'backend', 'en_US', array(3));
#&gt; 3 registered users</programlisting></para>
          </example><example>
            <title>Formatting currencies and numbers</title>

            <para><programlisting>$tm-&gt;_c(5000);
#&gt; 5.000,00 $

$tm-&gt;_c(5000.12345);
#&gt; 5.000,12 $

$tm-&gt;_c('12345678901234567890.98765');
#&gt; 12.345.678.901.234.567.890,99 $

$tm-&gt;_c(5000.12345, null, 'en_US@currency=EUR');
#&gt; €5,000.12

$tm-&gt;_n(5000.00);
#&gt; 5.000

$tm-&gt;_n(5000.12345);
#&gt; 5.000,12345

$tm-&gt;_n("12345678901234567890.98765", 'backend', 'en_US');
#&gt; 12,345,678,901,234,567,890.98765</programlisting></para>
          </example><example>
            <title>Formatting dates</title>

            <para><programlisting>$tm-&gt;_d(time());
#&gt; 08.12.2006 07:42:43

$tm-&gt;_d(time(), null, 'en_US');
#&gt; Dec 8, 2006 7:42:43 AM

$tm-&gt;_d(time(), 'backend');
#&gt; Freitag, 8. Dezember 2006 7:42 Uhr MEZ

$tm-&gt;_d(time(), 'backend', '@timezone=Europe/London');
#&gt; Freitag, 8. Dezember 2006 6:42 Uhr GMT+00:00

$tm-&gt;_d(time(), 'backend', 'en_US@timezone=Europe/London');
&gt;# Friday, December 8, 2006 6:42:43 AM Europe/London</programlisting></para>
          </example></para>
      </section>

      <section>
        <title></title>

        <para></para>
      </section>
    </section>

    <section id="databases">
      <title>Databases</title>

      <para>(how to retrieve a connection, why do it using the framework,
      propel)</para>

      <para>Unlike many other frameworks Agavi doesn't have a database layer
      of its own but it supports a variety of different database layers and
      APIs. Currently the following APIs and tools are supported</para>

      <itemizedlist>
        <listitem>
          <para>AdoDB (<link linkend="???"><ulink
          url="http://adodb.sourceforge.net/">http://adodb.sourceforge.net/</ulink></link>)</para>
        </listitem>

        <listitem>
          <para>Creole (<ulink
          url="http://creole.phpdb.org/">http://creole.phpdb.org/</ulink>)</para>
        </listitem>

        <listitem>
          <para>PDO (<ulink
          url="http://www.php.net/pdo">http://www.php.net/pdo</ulink>)</para>
        </listitem>

        <listitem>
          <para>PHP's native Mysql API</para>
        </listitem>

        <listitem>
          <para>PHP's native Postgresql API</para>
        </listitem>

        <listitem>
          <para>Propel (<ulink
          url="http://propel.phpdb.org/">http://propel.phpdb.org/</ulink>)</para>
        </listitem>
      </itemizedlist>

      <para>Your options are however not limited to these because integrating
      your favourite database tool with Agavi is fairly simple.</para>

      <para>Each database implementation is wrapped into a class extending
      <classname>AgaviDatabase</classname>.</para>

      <section id="databases-connection-configuration">
        <title>Database Connection Configuration</title>

        <para>Database connections are configured in
        <filename>app/config/databases.xml. You can have more than one
        connections.</filename></para>

        <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configurations xmlns="http://agavi.org/agavi/1.0/config"&gt;
  &lt;configuration&gt;
    &lt;databases default="postgres"&gt;

      &lt;database name="postgres" class="AgaviPostgresqlDatabase"&gt;
        &lt;parameters&gt;
          &lt;parameter name="host"&gt;localhost&lt;/parameter&gt;
          &lt;parameter name="username"&gt;username&lt;/parameter&gt;
          &lt;parameter name="password"&gt;passphrase&lt;/parameter&gt;
          &lt;parameter name="database"&gt;sample&lt;/parameter&gt;
        &lt;/parameters&gt;
      &lt;/database&gt;

      &lt;database name="propel" class="AgaviPropelDatabase"&gt;
        &lt;parameters&gt;
          &lt;parameter name="config"&gt;%core.app_dir%/config/project-conf.php&lt;/parameter&gt;
        &lt;/parameters&gt;
      &lt;/database&gt;

    &lt;/databases&gt;
  &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting>
      </section>

      <section id="databases-using-the-connection">
        <title>Using the Connection</title>

        <para>Database connections are retrieved using
        <classname>AgaviDatabaseManager</classname>.</para>

        <programlisting>// retrieve the handle of the default database connection
$conn = $this-&gt;context-&gt;getDatabaseManager()-&gt;getDatabase();
// retrieve the handle of a named database connection
$conn2 = $this-&gt;context-&gt;getDatabaseManager()-&gt;getDatabase('second_database');

// AgaviContext also has a shorcut. You can use it for named connections too.
$conn2 = $this-&gt;context-&gt;getDatabaseConnection();</programlisting>
      </section>
    </section>

    <section id="logging">
      <title>Logging</title>

      <para>why logging, how to do it, levels, loggers, appenders,
      layouts</para>
    </section>
  </chapter>

  <chapter id="agavi-reference">
    <title>Agavi Reference</title>

    <section id="ref-agavi">
      <title>Controller</title>

      <para><variablelist>
          <varlistentry>
            <term>Naming</term>

            <listitem>
              <para><classname>[ModuleName_][SubSection_]NameController</classname></para>

              <para>Example:
              <classname>MyModule_Sub_EditController</classname></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Execute Methods</term>

            <listitem>
              <para><methodname>execute[Method](AgaviParameterHolder
              parameters)</methodname></para>

              <para>Agavi tries to use the execute method specific to the
              current request method (e.g.
              <methodname>executeRead</methodname> or
              <methodname>executeWrite</methodname>). If such a method is not
              defined by the current controller a generic execute is used. If that
              doesn't exist either execution and validation is skiped and the
              default view (returned by
              <methodname>getDefaultViewName()</methodname>) is used.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Validation Methods</term>

            <listitem>
              <para><methodname>register[Method]Validators(AgaviValidatorManager
              validatorManager)</methodname></para>

              <para></para>

              <para><methodname>validate[Method](AgaviParameterHolder
              parameters)</methodname></para>

              <para></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Error Handlers</term>

            <listitem>
              <para></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Default View Name</term>

            <listitem>
              <para></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Request Parameters</term>

            <listitem>
              <para></para>
            </listitem>
          </varlistentry>
        </variablelist></para>
    </section>

    <section id="ref-configuration">
      <title>Configuration</title>

      <para></para>
    </section>

    <section id="ref-controller">
      <title>Dispatcher</title>

      <para></para>
    </section>

    <section id="ref-core-context">
      <title>Core/Context</title>

      <para></para>
    </section>

    <section id="ref_databases">
      <title>Databases</title>

      <para></para>
    </section>

    <section id="ref-exceptions">
      <title>Exceptions</title>

      <para></para>
    </section>

    <section id="ref-filters">
      <title>Filters</title>

      <para></para>
    </section>

    <section id="ref-logging">
      <title>Logging</title>

      <para></para>
    </section>

    <section id="ref-models">
      <title>Models</title>

      <para></para>
    </section>

    <section id="ref-renderers">
      <title>Renderers</title>

      <para></para>
    </section>

    <section id="ref-request">
      <title>Request</title>

      <para></para>
    </section>

    <section id="ref-response">
      <title>Response</title>

      <para></para>
    </section>

    <section id="ref-routing">
      <title>Routing</title>

      <para></para>
    </section>

    <section id="ref-storage">
      <title>Storage</title>

      <para></para>
    </section>

    <section id="ref-translation">
      <title>Translation</title>

      <para></para>

      <section>
        <title id="ref_translation_configuration">Configuration via
        translation.xml</title>

        <para></para>
      </section>

      <section id="reference-translation-define_available_locales">
        <title>Defining available locales</title>

        <para></para>
      </section>

      <section id="reference-translation-set_current_locale">
        <title>Setting the current locale</title>

        <para></para>
      </section>

      <section id="reference-translation-translation_methods">
        <title>Methods being used for translation</title>

        <para></para>
      </section>

      <section id="reference-translation-custom_message_translators">
        <title>Writing custom message translators</title>

        <para></para>
      </section>

      <section id="reference-translation-overwrite_cldr_data">
        <title>Overwriting the data from the CLDR</title>

        <para></para>
      </section>
    </section>

    <section id="ref-user">
      <title>User</title>

      <para></para>
    </section>

    <section id="ref-validation">
      <title>Validation</title>

      <para></para>
    </section>

    <section id="ref-views">
      <title>Views</title>

      <para></para>
    </section>
  </chapter>

  <chapter id="configuration-handler-tag-reference">
    <title>Configuration handler tag reference</title>

    <section id="reference-configuration_tags-general">
      <title>General Tags</title>

      <section id="ref_configuration_keywords">
        <title>Keywords</title>

        <para>You may reference any configuration directive by enclosing the
        name in "%" signs. Example: %core.agavi_dir%</para>
      </section>

      <section id="reference-configuration_tags-general_configurations">
        <title>&lt;configurations&gt;</title>

        <para>The &lt;configurations&gt; tag is the root tag of all Agavi XML
        configuration files.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>parent</optional></term>

                <listitem>
                  <para>A full path to a file which can be used to define
                  default configuration options. You can use <link
                  linkend="ref_configuration_keywords">keywords</link>
                  here.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;<link
                linkend="reference-configuration_tags-general_configuration">configuration</link>&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-general_configuration">
        <title>&lt;configuration&gt;</title>

        <para>Within the &lt;configuration&gt; block you can define
        configuration options which are only effective in the
        context/environment combination. Specifying one (or both) of the
        attributes limits that block to both the context and environment
        specified. You can actually define several configuration blocks in the
        root tag. <note>
            <para>Most configuration handlers allow selective overwriting of
            single attributes. So you can define a <link
            linkend="reference-configuration_tags-filterhandler_filters_filter">filter</link>
            with all parameters it needs and just disable it for certain
            contexts without having to specify the parameters or any of the
            attributes your already specified again.</para>
          </note></para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>context</optional></term>

                <listitem>
                  <para>The name of the context for which this configuration
                  block is valid.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>environment</optional></term>

                <listitem>
                  <para>The name of the environment this configuration block
                  is valid in.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The available child tags depend on the configuration handler
          which is used. <variablelist>
              <varlistentry>
                <term>autoload.xml</term>

                <listitem>
                  <para>autoloads</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>compile.xml</term>

                <listitem>
                  <para>compiles</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>config_handlers.xml</term>

                <listitem>
                  <para>handlers</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>databases.xml</term>

                <listitem>
                  <para>databases</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>factories.xml</term>

                <listitem>
                  <para>controller, database_manager, dispatch_filter
                  execution_container, execution_filter, filter_chain,
                  logger_manager, request, response, routing, security_filter,
                  storage, translation_manager, user, validator_manager</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>*_filters.xml</term>

                <listitem>
                  <para>filters</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>logging.xml</term>

                <listitem>
                  <para>loggers, appenders, layout</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>module/config/module.xml</term>

                <listitem>
                  <para>enabled, title, version, name, authors, homepage,
                  update_url, description</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>output_types.xml</term>

                <listitem>
                  <para>output_types</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>rbac_definitions.xml</term>

                <listitem>
                  <para>roles</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>routing.xml</term>

                <listitem>
                  <para>routes</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>settings.xml</term>

                <listitem>
                  <para>exception_templates, settings, system_controllers</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>translation.xml</term>

                <listitem>
                  <para>available_locales, translators</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>validators.xml</term>

                <listitem>
                  <para>defaults, validators</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-autoloadhandler">
      <title>AutoloadConfigHandler Tags (autoload.xml)</title>

      <para>The AutoloadConfigHandler allows you to define classes and their
      files to be automatically loaded by PHP when the class is first accessed
      (not in advance so there's no performance hit). This frees you from
      manually including it in your files.<example>
          <title>autoload.xml</title>

          <para><programlisting>&lt;configurations parent="%core.system_config_dir%/autoload.xml"&gt;
 &lt;configuration&gt;

  &lt;autoloads&gt;
   &lt;autoload name="AgaviSampleAppCookieLoginFilter"&gt;%core.lib_dir%/filter/AgaviSampleAppCookieLoginFilter.class.php&lt;/autoload&gt;
   &lt;autoload name="AgaviSampleAppLanguageRoutingCallback"&gt;%core.lib_dir%/routing/AgaviSampleAppLanguageRoutingCallback.class.php&lt;/autoload&gt;
   &lt;autoload name="AgaviSampleAppUser"&gt;%core.lib_dir%/user/AgaviSampleAppUser.class.php&lt;/autoload&gt;
  &lt;/autoloads&gt;

 &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting></para>
        </example></para>

      <para></para>

      <section id="reference-configuration_tags-autoloadhandler_autoloads">
        <title>&lt;autoloads&gt;</title>

        <para>Parent element for &lt;autoload&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;autoload&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-autoloadhandler_autoloads_autoload">
        <title>&lt;autoload&gt;</title>

        <para>Defines an autoload for a class.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of the class.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The full path to the file to be loaded when the class is
          needed. You can use <link
          linkend="ref_configuration_keywords">keywords</link> here.</para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-compilehandler">
      <title>CompileConfigHandler Tags (compile.xml)</title>

      <para>The CompileConfigHandler enables you to combine several files
      stripped of comments and blank lines into one single cache file. <note>
          <para>When you change one of your classes it will not be reflected
          in the cache file until you remove the cache file or you change the
          modified time of this file.</para>
        </note>The following example takes the files MyUtilityClass1 and
      MyUtilityClass2 in the util/ directory of your application and appends
      their contents to the content of base compile.xml cache file of
      Agavi.<example>
          <title>compile.xml</title>

          <para><programlisting>&lt;configurations parent="%core.system_config_dir%/compile.xml"&gt;
 &lt;configuration&gt;

  &lt;compiles&gt;
   &lt;compile&gt;%core.app_dir%/util/MyUtilityClass1.class.php&lt;/compile&gt;
   &lt;compile&gt;%core.app_dir%/util/MyUtilityClass2.class.php&lt;/compile&gt;
  &lt;/compiles&gt;

 &lt;/configuration&gt;
&lt;/configurations&gt;</programlisting></para>
        </example></para>

      <section id="reference-configuration_tags-compilehandler_compiles">
        <title>&lt;compiles&gt;</title>

        <para>Parent element for &lt;compile&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;compile&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-compilehandler_compiles_compile">
        <title>&lt;compile&gt;</title>

        <para></para>

        <simplesect>
          <title>Content</title>

          <para>A full path to the file to be added to the compilation. You
          can use <link linkend="ref_configuration_keywords">keywords</link>
          here.</para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-confighandlershandler">
      <title>ConfigHandlersConfigHandler Tags (config_handlers.xml)</title>

      <para>Allows you to define your own configuration files.</para>

      <para>When you specify a relative path in the pattern the core.app_dir
      setting is used as the base path. <note>
          <para>When including the configuration file via
          AgaviConfigCache::checkConfig you need to specify the path in the
          same way as in the pattern (relative or absolute).</para>
        </note><warning>
          <para>When specifying the absolute path (which is the preferred way
          for consistence) use the <link
          linkend="ref_configuration_keywords">keywords</link> where
          appropriate.</para>
        </warning><example>
          <title>config_handlers.xml</title>

          <para><programlisting>&lt;configurations parent="%core.system_config_dir%/config_handlers.xml"&gt;
 &lt;configuration&gt;

  &lt;handlers&gt;
   &lt;handler pattern="%core.module_dir%/*/config/controller_filters.xml" validate="%core.agavi_dir%/config/xsd/filters.xsd" class="AgaviFilterConfigHandler" /&gt;
   &lt;handler pattern="%core.module_dir%/*/config/module.xml" validate="%core.agavi_dir%/config/xsd/module.xsd" class="AgaviModuleConfigHandler" /&gt;
   &lt;handler pattern="%core.module_dir%/*/validate/*.xml" class="AgaviValidatorConfigHandler" /&gt;
  &lt;/handlers&gt;

 &lt;/configuration&gt;
&lt;/configurations&gt;
</programlisting></para>
        </example></para>

      <section id="reference-configuration_tags-confighandlershandler_handlers">
        <title>&lt;handlers&gt;</title>

        <para>Parent element for &lt;handler&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;handler&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-confighandlershandler_handlers_handler">
        <title>&lt;handler&gt;</title>

        <para>Defines a configuration handler.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class (name) providing the handler implementation
                  for files match the pattern.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>pattern</term>

                <listitem>
                  <para>A file path pattern. Use * as a placeholder. You can
                  use <link
                  linkend="ref_configuration_keywords">keywords</link>
                  here.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>parser</optional></term>

                <listitem>
                  <para>You can define an alternative parser class (name)
                  here. Use this if you don't want to use the default parser
                  (in sense of default parser for that extension, "autosensed"
                  by agavi) for that configuration file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>validate</optional></term>

                <listitem>
                  <para>A file path to a validation file (.xsd for .xml
                  configuration files). You can use <link
                  linkend="ref_configuration_keywords">keywords</link> here.
                  If not specified the configuration file will not be
                  validated before being passed to the configuration
                  handler.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-databasehandler">
      <title>DatabaseConfigHandler Tags (databases.xml)</title>

      <para>Registers database connections with the system. You have to
      specify a default connection to be used. The available parameters for
      the different database types are explained in the <link
      linkend="ref_databases">databases reference</link>.<example>
          <title>databases.xml</title>

          <para><programlisting>&lt;configurations&gt;
 &lt;configuration&gt;

  &lt;databases default="propel"&gt;
   &lt;database name="postgres" class="AgaviPostgresqlDatabase"&gt;
    &lt;parameters&gt;
     &lt;parameter name="host"&gt;localhost&lt;/parameter&gt;
     &lt;parameter name="username"&gt;username&lt;/parameter&gt;
     &lt;parameter name="password"&gt;passphrase&lt;/parameter&gt;
     &lt;parameter name="database"&gt;sample&lt;/parameter&gt;
    &lt;/parameters&gt;
   &lt;/database&gt;

   &lt;database name="propel" class="AgaviPropelDatabase"&gt;
    &lt;parameters&gt;
     &lt;parameter name="config"&gt;%core.app_dir%/config/project-conf.php&lt;/parameter&gt;
    &lt;/parameters&gt;
   &lt;/database&gt;
  &lt;/databases&gt;

 &lt;/configuration&gt;
&lt;/configurations&gt;
</programlisting></para>
        </example></para>

      <section id="reference-configuration_tags-databasehandler_databases">
        <title>&lt;databases&gt;</title>

        <para>Parent element for &lt;database&gt;</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>default</term>

                <listitem>
                  <para>The name (as specified in the name attribute of the
                  &lt;database&gt; element) of the default database
                  connection.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;database&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-databasehandler_databases_database">
        <title>&lt;database&gt;</title>

        <para>A database connection.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class which implements the database
                  connection.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this connection.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-factoryhandler">
      <title>FactoryConfigHandler Tags (factories.xml)</title>

      <para>In the FactoryConfigHandler all child tags have the same possible
      attributes and child tags.</para>

      <section>
        <title>&lt;*&gt;</title>

        <para>Available elements are <simplelist type="inline">
            <member>"controller"</member>

            <member>"database_manager"</member>

            <member>"dispatch_filter"</member>

            <member>"execution_container"</member>

            <member>"execution_filter"</member>

            <member>"logger_manager"</member>

            <member>"request"</member>

            <member>"response"</member>

            <member>"routing"</member>

            <member>"security_filter"</member>

            <member>"storage"</member>

            <member>"translation_manager"</member>

            <member>"user"</member>

            <member>"validator_manager"</member>
          </simplelist></para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The implementing class.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-filterhandler">
      <title>FilterConfigHandler Tags (*_filters.xml)</title>

      <para>You may use <filename>controller_filters.xml</filename> and
      <filename>global_filters.xml</filename> to configure filters that wrap
      either the global execution flow or individual controllers. Controller filters
      may also be specified on a per-module basis by putting them into the
      <filename>app/modules/ModuleName/config/</filename> folder.</para>

      <section id="reference-configuration_tags-filterhandler_filters">
        <title>&lt;filters&gt;</title>

        <para>Parent element for &lt;filter&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;filter&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-filterhandler_filters_filter">
        <title>&lt;filter&gt;</title>

        <para>Defines a filter.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this filter.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class implementing this filter.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>enabled</optional></term>

                <listitem>
                  <para>Whether this filter should be enabled. Defaults to
                  <emphasis>true</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-logginghandler">
      <title>LoggingConfigHandler Tags (logging.xml)</title>

      <para>This configuration file is used to specify loggers, their
      appenders and so on.</para>

      <section id="reference-configuration_tags-logginghandlers_loggers">
        <title>&lt;loggers&gt;</title>

        <para>Parent element for &lt;logger&gt;</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>default_logger</optional></term>

                <listitem>
                  <para>The name of the default logger. Defaults to
                  <emphasis>default</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;logger&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_loggers_logger">
        <title>&lt;logger&gt;</title>

        <para>Defines a logger instance.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of the logger instance.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class implementing this logger instance.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>level</optional></term>

                <listitem>
                  <para>The levels which should be logged. You need to
                  specifiy the full constants names (AgaviLogger::DEBUG, ...)
                  and can use bitwise operators to include several
                  levels.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1 &lt;<link
                linkend="reference-configuration_tags-logginghandlers_loggers_logger_appenders">appenders</link>&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_loggers_logger_appenders">
        <title>&lt;logger&gt;/&lt;appenders&gt;</title>

        <para>Parent element for &lt;appender&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;<link
                linkend="reference-configuration_tags-logginghandlers_loggers_logger_appenders_appender">appender</link>&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_loggers_logger_appenders_appender">
        <title>&lt;logger&gt;/&lt;appenders&gt;/&lt;appender&gt;</title>

        <para></para>

        <simplesect>
          <title>Content</title>

          <para>The name of the appender.</para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_appenders">
        <title>&lt;appenders&gt;</title>

        <para>Parent element for &lt;appender&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;appender&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_appenders_appender">
        <title>&lt;appender&gt;</title>

        <para>Defines an appender instance.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this appender</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The implementing class.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>layout</term>

                <listitem>
                  <para>The name of the layout which should be used.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_layouts">
        <title>&lt;layouts&gt;</title>

        <para>Parent element for &lt;layout&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;layout&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-logginghandlers_layouts_layout">
        <title>&lt;layout&gt;</title>

        <para>Defines a layout instance.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this layout instance.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The implementing class.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-outputtypehandler">
      <title>OutputTypeConfigHandler Tags (output_types.xml)</title>

      <para>Used to configure Output Types.</para>

      <section>
        <title
        id="reference-configuration_tags-outputtypehandler_output_types">&lt;output_types&gt;</title>

        <para>Parent element for &lt;output_type&gt;</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>default</term>

                <listitem>
                  <para>The default output type.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;output_type&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-outputtypehandler_output_types_output_type">
        <title>&lt;output_type&gt;</title>

        <para>Defines an output type.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this output type.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1 &lt;renderer&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-outputtypehandler_output_types_output_type_renderer">
        <title>&lt;renderer&gt;</title>

        <para>Defines the renderer and options.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The renderer class.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>extension</optional></term>

                <listitem>
                  <para>The extension of the template files. Defaults differ
                  for each renderer.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>ignore_decorators</optional></term>

                <listitem>
                  <para>Whether to ignore any decorators for this output type.
                  Defaults to <emphasis>false</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>ignore_slots</optional></term>

                <listitem>
                  <para>Whether to ignore any slots. Defaults to
                  <emphasis>false</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>
    </section>

    <section>
      <title>RbacDefinitionConfigHandler Tags (e.g.
      rbac_definitions.xml)</title>

      <para>This config handler can parse simple RBAC role definition config
      files.</para>

      <section>
        <title>&lt;roles&gt;</title>

        <para>Contains a list of roles.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;role&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section>
        <title>&lt;role&gt;</title>

        <para>Defines permissions and may contain child roles.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>name</optional></term>

                <listitem>
                  <para>The name that identifies the role.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;roles&gt;</para>
              </listitem>

              <listitem>
                <para>1 &lt;pernissions&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section>
        <title>&lt;permissions&gt;</title>

        <para>Contains one or more permissions for a role.</para>
      </section>

      <section>
        <title>&lt;permission&gt;</title>

        <para>Specifies the name of a credential the user will be given when
        he is assigned to the respective role.</para>

        <simplesect>
          <title>Content</title>

          <para>The name of the credential the user will be given.</para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-routinghandler">
      <title>RoutingConfigHandler Tags (routing.xml)</title>

      <para>Used to configure routing rules.</para>

      <section id="reference-configuration_tags-routinghandler_routes">
        <title>&lt;routes&gt;</title>

        <para>Parent element for &lt;route&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-n &lt;route&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-routinghandler_routes_route">
        <title>&lt;route&gt;</title>

        <para>Defines a route to an module/controller pair.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this route.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>pattern</term>

                <listitem>
                  <para>The pattern.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>module</optional></term>

                <listitem>
                  <para>The module which should be used when this route
                  matches.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>controller</optional></term>

                <listitem>
                  <para>The controller which should be used when this route
                  matches.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>locale</optional></term>

                <listitem>
                  <para>The locale to be set when this route matches.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>method</optional></term>

                <listitem>
                  <para>The request method to be set when this route
                  matches.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>output_type</optional></term>

                <listitem>
                  <para>The output type to be set when this route
                  matches.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>callback</optional></term>

                <listitem>
                  <para>A class name of a class implementing the
                  AgaviRoutingCallback methods.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>constraint</optional></term>

                <listitem>
                  <para>The request method for which this route is
                  valid.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>cut</optional></term>

                <listitem>
                  <para>Whether the matched pattern should be removed from the
                  routing input when the route matches. Defaults to
                  <emphasis>false</emphasis> when the route doesn't have
                  children and to <emphasis>true</emphasis> otherwise.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>imply</optional></term>

                <listitem>
                  <para>Whether this route should always be generated in the
                  output when using $routing-&gt;gen(). Defaults to
                  <emphasis>false</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>stop</optional></term>

                <listitem>
                  <para>Whether execution of further routes should stop when
                  this route matched. This can not be set to false for routes
                  with child routes. Defaults to
                  <emphasis>true</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>source</optional></term>

                <listitem>
                  <para>The source which should be used as the input for this
                  route. Defaults to the request URI.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;defaults&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;ignores&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-routinghandler_routes_route_ignores">
        <title>&lt;ignores&gt;</title>

        <para>Allows you to define which parameters from the pattern should be
        included in the request parameters. Acts as parent element for
        &lt;ignore&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;ignore&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-routinghandler_routes_route_ignores_ignore">
        <title>&lt;ignore&gt;</title>

        <para>Defines a parameter to be ignored.</para>

        <simplesect>
          <title>Content</title>

          <para>The name of the parameter to be ignored.</para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-routinghandler_routes_route_defaults">
        <title>&lt;defaults&gt;</title>

        <para>Allows you to set default values for parameters of the pattern
        to be used when generating a route. These values will also be set into
        the request when the route matched but didn't contain a parameter with
        the name for which this default exists.</para>

        <para>Parent element for &lt;default&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;default&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-routinghandler_routes_route_defaults_default">
        <title>&lt;default&gt;</title>

        <para>Defines a default.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>for</term>

                <listitem>
                  <para>The name of the parameter this default applies
                  to.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The default value to be used. You can specify a default
          pre-/postfix by wrapping the value into {} (for example:
          "prefix{defaultValue}postfix").</para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-settinghandler">
      <title>SettingConfigHandler Tags (settings.xml)</title>

      <para></para>

      <section id="reference-configuration_tags-settinghandler_exception_templates">
        <title>&lt;exception_templates&gt;</title>

        <para>Parent element for &lt;exception_template&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;exception_template&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-settinghandler_exception_templates_exception_template">
        <title>&lt;exception_template&gt;</title>

        <para>Defines the exception template to use.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>context</optional></term>

                <listitem>
                  <para>Limits the template to the given context</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The full path to the template. You can use <link
          linkend="ref_configuration_keywords">keywords</link> here.</para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-settinghandler_settings">
        <title>&lt;settings&gt;</title>

        <para>Parent element for &lt;setting&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;setting&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-settinghandler_settings_setting">
        <title>&lt;setting&gt;</title>

        <para>Defines a setting. To access a setting in your code use
        AgaviConfig::get('core.setting_name');</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of the setting.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The value of the setting. You can use <link
          linkend="ref_configuration_keywords">keywords</link> here.</para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-settinghandler_system_controllers">
        <title>&lt;system_controllers&gt;</title>

        <para></para>

        <simplesect>
          <title>Attributes</title>

          <para></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-settinghandler_system_controllers_system_controller">
        <title>&lt;system_controller&gt;</title>

        <para></para>

        <simplesect>
          <title>Attributes</title>

          <para></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para></para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-translationhandler">
      <title>TranslationConfigHandler Tags (translation.xml)</title>

      <para>In this configuration file, you can configure the available
      locales, translation domains as well as translators and their
      settings.</para>

      <section id="reference-configuration_tags-translationhandler_available_locales">
        <title>&lt;available_locales&gt;</title>

        <para>Defines which locales are available for use by the
        application.</para>

        <para>Parent element for &lt;available_locale&gt;.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>default_locale</optional></term>

                <listitem>
                  <para>Sets the default locale to be used.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>default_timezone</optional></term>

                <listitem>
                  <para>Sets the default timezone to be used by the Agavi
                  calendar system. This doesn't affect the timezone setting of
                  PHP.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;available_locale&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_available_locales_available_locale">
        <title>&lt;available_locale&gt;</title>

        <para>Defines an available locale.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>identifier</term>

                <listitem>
                  <para>The locale identifier.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators">
        <title>&lt;translators&gt;</title>

        <para>Defines the translation domains.</para>

        <para>Parent element for &lt;translator&gt;.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>default_domain</term>

                <listitem>
                  <para>The default domain used when translating.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;translator&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators_translator">
        <title>&lt;translator&gt;</title>

        <para>Defines a translation domain.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>domain</term>

                <listitem>
                  <para>The name of this domain.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;message_translator&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;number_formatter&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;currency_formatter&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;date_formatter&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators_translator_message_translator">
        <title>&lt;message_translator&gt;</title>

        <para>Defines the translator to be used when translating strings in
        this domain.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>type</term>

                <listitem>
                  <para>The type (class name for custom implementations) of
                  this translator.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;filters&gt;</para>
              </listitem>
            </itemizedlist></para>

          <para></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators_translator_number_formatter">
        <title>&lt;number_formatter&gt;</title>

        <para>Defines the formatter to be used when formatting numbers.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>type</term>

                <listitem>
                  <para>The type (class name for custom implementations) of
                  this formatter.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators_translator_currency_formatter">
        <title>&lt;currency_formatter&gt;</title>

        <para>Defines the formatter to be used when formatting
        currencies.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>type</term>

                <listitem>
                  <para>The type (class name for custom implementations) of
                  this formatter.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_translators_translator_date_formatter">
        <title>&lt;date_formatter&gt;</title>

        <para>Defines the formatter to be used when formatting dates.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>type</term>

                <listitem>
                  <para>The type (class name for custom implementations) of
                  this formatter.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_filters">
        <title>&lt;filters&gt;</title>

        <para>Parent element for &lt;filter&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;filter&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-translationhandler_filters_filter">
        <title>&lt;filter&gt;</title>

        <para>Defines a filter for translator or formatter.</para>

        <simplesect>
          <title>Content</title>

          <para>The function implementing this filter. You can define static
          class methods by using the "class::method" syntax</para>
        </simplesect>
      </section>
    </section>

    <section id="reference-configuration_tags-validatorhandler">
      <title>ValidatorConfigHandler Tags (validate/*.xml)</title>

      <para>Validation files sit inside
      <filename>app/modules/ModuleName/validate/</filename>, with the file
      name consisting of the Controller name and the <filename>.xml</filename>
      extension.</para>

      <section id="reference-configuration_tags-validatorhandler_validator_definitions">
        <title>&lt;validator_definitions&gt;</title>

        <para>Parent element for &lt;validator_definition&gt;.</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;validator_definition&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validator_definitions_validator_definition">
        <title>&lt;validator_definition&gt;</title>

        <para>Defines an alias and default parameters for a validator.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>A name which can be used instead of the class name
                  when referring to this validator.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class implementing this validator.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators">
        <title>&lt;validators&gt;</title>

        <para>Parent element for &lt;validator&gt;</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>method</optional></term>

                <listitem>
                  <para>The method to limit the child validators to</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>severity</optional></term>

                <listitem>
                  <para>The default severity of the child validators.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;validator&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators_validator">
        <title>&lt;validator&gt;</title>

        <para>Defines a validator.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term>name</term>

                <listitem>
                  <para>The name of this validator.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>class</term>

                <listitem>
                  <para>The class or alias implementing this validator.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>method</optional></term>

                <listitem>
                  <para>The request method(s, delimited by space) in which
                  this validator should be run.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>required</optional></term>

                <listitem>
                  <para>Whether the value is required.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><optional>severity</optional></term>

                <listitem>
                  <para>The severity which will be used when this validator
                  fails.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>0-1 &lt;arguments&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;errors&gt;</para>
              </listitem>

              <listitem>
                <para>0-1 &lt;parameters&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators_validator_arguments">
        <title>&lt;arguments&gt;</title>

        <para>Parent element for &lt;argument&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;argument&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators_validator_arguments_argument">
        <title>&lt;argument&gt;</title>

        <para>Defines an argument to be validated.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>name</optional></term>

                <listitem>
                  <para>The name of this argument (usage depends on the
                  validator).</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The name of the request parameter which contains the argument
          to be validated</para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators_validator_errors">
        <title>&lt;errors&gt;</title>

        <para>Parent element for &lt;error&gt;</para>

        <simplesect>
          <title>Content</title>

          <para><itemizedlist>
              <listitem>
                <para>1-n &lt;error&gt;</para>
              </listitem>
            </itemizedlist></para>
        </simplesect>
      </section>

      <section id="reference-configuration_tags-validatorhandler_validators_validator_errors_error">
        <title>&lt;error&gt;</title>

        <para>Defines an error message.</para>

        <simplesect>
          <title>Attributes</title>

          <para><variablelist>
              <varlistentry>
                <term><optional>for</optional></term>

                <listitem>
                  <para>Using the for attribute you can specify different
                  error messages for different types of errors which depend on
                  the validator used.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </simplesect>

        <simplesect>
          <title>Content</title>

          <para>The error message.</para>
        </simplesect>
      </section>
    </section>
  </chapter>
</book>