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

Installing Agavi

Prerequisites

Agavi's minimum requirement is PHP version 5.2.0 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 distributions made by "smart" people who think they know better. You'll find a full list of required and optional extensions below.

Note: 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.

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 (IIS) have been tested and verified to be compatible with the framework and it's components, such as the routing. Other web servers are likely to work as well, maybe with some minor extensions to the framework.

Installation via PEAR requires the PEAR client, which comes with most PHP distributions. Installation from Subversion repository requires a Subversion client. grab it straight from the SVN repository, you'll need a Subversion client installed. The project manager system requires Phing, which is a PHP based clone of Java Ant.


  • PHP > 5.2.0, we recommend to keep your system up to date and use a recent version. Please note that some features are not supported in PHP versions < 5.2.8, most importantly running on a system with magic_quotes_gpc enabled is not possible as there are major bugs in how uploaded files are processed.
  • libxml
  • dom
  • SPL
  • Reflection
  • pcre
  • xsl (optional) required only for transformation of pre 1.0 style configuration files.
  • tokenizer (optional) used to generate more efficient config-caches.
  • session (optional) no php session support means that you'll have to build your own session storage system and hook it into agavi.
  • xmlrpc (optional) required for XML-RPC features
  • soap (optional) required for SOAP features
  • PDO (optional) required for database connectors that use PDO as base
  • iconv (optional)
  • gettext (optional) required to use gettext-translators in the interationalization feature.
  • PHING >= 2.3.1 (optional) required to use the build system.

Installation From PEAR

Installation with PEAR is relatively simple. Discover the Agavi PEAR channel and then install Agavi using the PEAR command line interface:

$ pear channel-discover pear.agavi.org

Adding Channel "pear.agavi.org" succeeded
Discovery of channel "pear.agavi.org" succeeded

$ pear config-set auto_discover 1
$ pear install -a agavi/agavi

It is also possible to obtain a specific version of Agavi:

  $ pear install agavi/agavi-0.11.0
Tip: 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.

Using a tarball

Installing Agavi by hand is the logical choice if you can't use PEAR, or if you seek to bundle Agavi with your application so that your users or customers do not have to install it separately. Download a release tarball from the Agavi website, unpack it somewhere and move the contents of the src folder to a location of your choice. Make sure to adjust PHP's include path to cover this location. Don't forget to copy bin/agavi-dist or bin/agavi.bat-dist script (for unix/linux/mac users and windows users respectively) to an agavi or agavi.bat executable into a convenient location so you can use the shell commands for creating projects, modules, actions etc. Keep in mind that you must edit the script and enter the path to your Agavi installation (that's the src folder you copied earlier) so everything works as intended.

The more usual case, however, will be that you're shipping Agavi together with your application, either because you can't use PEAR/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 src folder to somewhere inside your application's directory structure (we recommend a libs folder that holds all libraries your app uses and that sits on the same level as the app and pub directories) and give it a different name, agavi would stand to reason. For that little extra something, copy the agavi-dist or agavi.bat-dist script again, maybe to your application root. Then, your application'spub/index.php should be changed to use a relative path for including agavi.php, such as ../libs/agavi/agavi.php. Agavi will auto-determine and remember the path where it was loaded from, and will work without any changes to your environment's include path.

From SVN

Public access to the Subversion repository is possible via http://svn.agavi.org/. Specific releases are available through /agavi/tags. Development usually occurs in /branches, so if you're looking for a latest useful version, look there. /trunk contains the bleeding edge version that the core developers are working on at the moment. It is more likely than not to be broken at any given point of time, so don't use it unless you know what you're doing.

You can either perform an svn checkout, which creates .svn folders that allow you to stay up to date on changes in the repository via svn update, or you can simply svn export 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.

Once you have obtained a copy from the repository, you can either follow the manual installation procedure, or generate your own PEAR package to be installed by PEAR locally by doing:

  $ cd (agavi checkout path)
  $ pear channel-discover pear.agavi.org
  $ phing package-pear
  $ cd build/
  $ pear package
This will create a .tgz file which can be installed using PEAR. If you already have Agavi installed it might be a good idea to remove it first by running pear uninstall agavi/agavi.
Important: We recommend that you use only released versions for production use as they have gone through a full testing cylcle. We generally try not to break trunk or branches but sometimes it just happens. It's fine to install a development version if you just want to poke around and explore new features.

Testing your installation

A properly deployed Agavi installation enables the Agavi project configuration script, agavi. You should test that the installation worked correctly by executing agavi from the command line. This should provide some basic information about your current environment:

$ agavi
Agavi > status:

[echo] PHP:
[echo]   Version: 5.2.6-2
[echo]   Include path: .:/usr/share/php:/usr/share/pear
[echo]
[echo] Phing:
[echo]   Version: Phing version 2.3.1RC1
[echo]
[echo] Agavi:
[echo]   Installation directory: /usr/share/php/agavi
[echo]   Version: 1.0.1
[echo]   URL: http://www.agavi.org
[echo]
[echo] Project:
[echo]   (not found)
[echo]
[echo] For a list of possible build targets, call this script with the -l argument.
If you installed agavi by hand you might need to adjust the path to the agavi script. Note that version information may differ slightly. If you are getting errors instead, Agavi isn't installed correctly. If you can't figure out the problem yourself, don't hesitate to ask the core developers.