Mojavi is a fantastically lightweight, simple, and easy-to-use MVC framework for PHP. I have investigated most MVC frameworks out there, and most of them (Phrame, for one) suffer from the Java-wanna-be complex, which makes for a bloated and inefficient environment for a run-time scripting language like PHP. This tutorial assumes you have discovered Mojavi, downloaded the distribution for Mojavi 2.0 (still beta, but very stable), and looked around long enough to discover that good documentation is sorely lacking. This, of course, does not imply that what follows is "good documentation." Indeed, right now it is very much a rough draft. But I figure something is better than nothing. So here goes.

First, find or get your mojavi 2.0 installation. It should look something like this:

mojavi/
    index.php
    lib/
    mojavi-all-classes.php
    opt/
    webapp/

index.php is an example of the file you would put somewhere in your web folder. webapp/ is a sample Mojavi application, that, as of this writing, probably does not work out of the box, since development on Mojavi has continued to move very fast since the example application was created. Don't worry about that. Forgive the developers and move on. This webapp/ folder will give you a sense of what a Mojavi application will look like, and especially what the folder structure should be. If you have not done so, look at these aforementioned files, as it will help you understand the rest of this tutorial.

Update: I have created an example application with Mojavi-2.0b2 that should work out-of-the-box with only minor path adjustments The current example does not work seamlessly with the Mojavi 2.0 release due to some vagaries regarding error_reporting() levels. See the comments at the end of this article.

If you are like me, you generally cannot adopt any PHP code without first looking at the source code and understanding, on some level, the internals of what is going on, starting from A and ending with Z. So, if you want to look through the code, (and I highly recommend you do), start with the following list

1. index.php loads webapp/config.php and then creates a $controller which then calls
2. $controller->dispatch (see lib/Controller.class.php) which, after some boring details, calls
3. $controller->forward() (see lib/Controller.class.php) whose primary function is to load and call
4. ExecutionFilter::execute() (see lib/filters/ExecutionFilter.class.php) which is where most of the fun stuff happens.

The rest of this article is (hopefully) a somewhat illuminating article on how it all happens, in chronological order. For a visual diagram of Mojavi, that is really only useful once you "get it", go here. So, without further ado, let us start with what happens in the index.php file as found in the Mojavi 2.0 distribution.

The Controller is instantiated.

The controller in an MVC framework determines what gets executed when. In Mojavi, the controller passes on its control to actions which, after communicating with the model, tells what view should handle rendering. When the controller is instantiated, a couple of important things happen.

1. A request object is created.
2. A user object is created.

These three objects (the $controller, $request, and $user) are central to Mojavi and are seen quite often throughout all your code.

A $request object is created.

This object is very important and used often. It is the "bin" for any objects, renderers, models, etc. that you create that need to be "passed" from your Filters to Actions to Views, etc. A few examples of its usage:

/** Somewhere in your code, like YourFilter::execute() **/
$renderer =& new Renderer; //this is my page renderer instance
$request->setAttributeByRef('Renderer',$renderer);//now save a reference in $request so we can find and use this later...

/** Somewhere else in your code, like YourView::execute() **/
$r =& $request->getAttribute('Renderer'); // get the ref you saved previously...
$r->setAttribute('my_var','my_val');

In addition to the get/set Attribute methods, the same methods exist for parameters, which are Mojavi's name for user input (from a form or GET string, for example). A simple example:

if( $request->hasParameter('user_id') ) {
    //since the user_id is set
    //get user data from model
    //et.c
}

//you can also get/set parameters.
$user_id = $request->getParameter('user_id');//getting paramaters is used often, esp. in View

$unique_id = 'adsfj423432434';
$request->setParameter('unique_id', $unique_id);

//you can also set a param by ref
$request->setParameterByRef('big_object', $big_object);

A $user object is created

The $user object is necessary for authentication and is the container for all session management in Mojavi. If sessions are enabled in PHP, then $user will have the following capability:

$user->setAttribute('name', $name);//set 'name' in session.

$name =& $user->getAttribute('name');

To learn more about $user, look at lib/User.php and /opt/user/PrivilegeUser.php for explanation of the different methods available.

Controller is dispatched and forwards to a specified Action

Before continuing, it is important to understand that the building blocks for your Mojavi application are actions. Anything that you want to "do" in your application is encapsulated in your own Action object that extends the base Action class. Additionally, actions are grouped into modules.

How Mojavi maps a request

Now, all MVC frameworks require some sort of "mapping" so that the Front Controller knows which Actions to load to handle the request from the user. Mojavi's "mapping" is found in a strict but simple set of naming conventions. The easiest way to understand this is to look at the webapp/ directory inside your mojavi installation for a simple example, and to memorize the naming conventions.

Mojavi's $controller generally functions as a Front Controller, meaning that the command to be executed is determined by input to the program either through GET, POST, or PATH_INFO. So the $controller first determines the Action to be executed from the request, and then attempts to load in the Action located in:

BASE_DIR . 'modules/' . $moduleName . 'actions' . $actionName

If it cannot find and load that action successfully, it will then re-route to a PageNotFound module/action that you set in your config.php file. So, assuming all goes well

Controller forwards to the Action

Once Mojavi forwards to the correct action, a chain of "filters" are created. One of these filters (the last one) is Mojavi-specific; the rest can be created by you on both a global (all-modules) and module-specific level. Search Mojavi's forum for real-world examples of filters.

Global and Module Filters

Mojavi then creates an instance of a $filterChain object. Your filters are added to this chain in $filterChain and then a final filter (ExecutionFilter, found in filters/ExecutionFilter.class.php) is tacked on last at the end of the stack. Once this stack of filters has been created, $filterChain->execute() is called, which executes the first filter in the stack. Each filter then executes some code (perhaps setting up a DB connection, instantiating a template engine, etc.) and then calls the $filterChain->execute() method to send execution on to the next filter in the stack. Once this $filterChain has executed your custom filters, it then executes Mojavi's ExecutionFilter last. This is where everything "actually happens". A visual representation of this is found here.

Execution Filter

One of the best ways to understand how the logic in your MyAction class is executed, and how a corresponding view is created, is to analyze the ExecutionFilter::execute() method found in filters/ExecutionFilter.class.phpin the Mojavi 2.0 distribution. A visual representation of that method exists, but nothing compares to actually looking at the code.

Essentially, the ExecutionFilter asks your instantiated "MyAction" object a series of questions. Depending on the answers, certain methods of your MyAction object are called, like MyAction::execute(). This can be easily seen by looking at the ExecutionFilter::execute() code itself.

At this point, it might be a good idea to consult the diagram mentioned earlier for a visual idea of what is happening.

For example, the ExecutionFilter (EF) asks the question $myAction->isSecure(). Depending on the answer, an authentication routine is started (more on that some other day). If you don't specify that method in your extended MyAction class, then it will do as expected and return FALSE. The EF will also ask what request methods that your MyAction class serves with MyAction::getRequestMethods(). This can be none, get, or post (as specified in the constants REQNONE, REQGET, and REQ_POST, respectively). See the source code documentation for more details on the Action::getRequestMethods() function.

getRequestMethods

Now here's a sticky point that often confuses people. getRequestMethods() is an important method in your action because it specifies whether or not your Action should even attempt to execute. If getRequestMethods() does not return a value that matches the request's actual method (for example, if getRequestMethods() returns REQ_POST when the actual request method is REQ_GET) then your Action will not execute()! EF will call the Action::getDefaultView() method instead, and just render the view. What this basically means in layman terms, is that if, for example, you want to go to a "login" page, you first want to just see the form (i.e. the default view). You don't want to actually attempt to login (i.e. execute the LoginAction). You want to do that when the form is posted. So in this case, LoginAction::getRequestMethods() would look like:

function getRequestMethods() {
    return REQ_POST;//only call LoginAction::execute() if we are posting to this action.
}

function getDefaultView() {
    return VIEW_INPUT;//we want to send the request on to views/LoginView_input.class.php
}

Thus, LoginAction would first display the input view (with the form) and then when it was actually posted, LoginAction would then execute the requisite logic to "login."

Confused yet? I'm not surprised. Again, all of this sounds difficult, but it's actually not. Just start playing with some examples and within a few hours you'll be up and running.

Once the ExecutionFilter (EF) determines if the Action serves the right request method, it first validates the request. Your action has two methods related to this, registerValidators() and validate(). To learn how to validate a request, search the mojavi forum for topics on validate.

And then, finally, if the Action validates, your Action::execute() method is called. Here is where you would save user input to a database, for example. Once you have executed the business logic of your application, you need to tell the ExecutionFilter which view to render. So you return either a VIEW constant (see below), or a "string". This "string" follows the naming conventions mentioned earlier. Views have the following naming scheme: TheActionNameView_thestring.class.php. So, for example, if your Action::execute() method looks like this:

function execute(&$controller, &$request, &$user) {
    //store to a DB and then display the 'success' view

    return "saved";
}

The EF would then attempt to load the view called views/MyActionView_saved.class.php. Mojavi has created several constants that handle most possible views you would want to display. See lib/User.class.php for the complete list. Here are the most common:

• VIEW_INPUT -- literally "input"
• VIEW_SUCCESS -- literally "success"
• VIEW_ERROR
• VIEW_INDEX

Once the ExecutionFilter knows which view you want to initialize, it loads in the view and executes it (e.g. MyView::execute()). This execute() method returns a valid Renderer object (an interface class to customize to your template of choice), and then executes that Renderer object, which (finally) prints to STDOUT.

Whew! If you're confused still, don't fret. Just download an example of Mojavi, look around, spend five minutes debugging it until you get your include paths right, and you'll be surprised how quickly it begins to make a surprising amount of sense. It is by far the easiest MVC framework to implement and learn that I have come across.