Directory and Include Path Setup

Setting up OpenAvanti is simple. First, make sure you have a copy of the source code. You can get it from here

The simple answer of how to install: place the code in a directory somewhere, and make sure your application has access to it (preferably through a well constructed include path).

For more details, continue reading.

Where do I put the code?

We’re going to assume that you’ve downloaded the source code for OpenAvanti to use in a PHP application, and that you already have a directory set up for your application on your web server. There are a few options when considering where to place the code:

  1. You could place the OpenAvanti source code in the directory where you store all of your other PHP classes for the application. This works fine, however, it can make your directory cluttered and make it difficult to find classes. It also makes upgrading difficult when you have many projects, each with their own copy of the framework.
  2. The OpenAvanti code could be stored one directory deeper than the rest of your PHP classes, allowing separation between framework and application files. For example,if all of your classes are in a directory called classes, you could storeOpenAvanti in classes/openavanti. This, however, makes it difficult to upgade to new versions of OpenAvanti when you have many projects using it, as each project will have to have the framework files overwritten project by project.
  3. You could also store the OpenAvanti source code somewhere else in the system, away from the projects, and reference it. This is a good option if you don’t want to have to store a copy of OpenAvanti per project, but instead, allow all projects to reference the same base code. However, this makes it difficult when upgrading as all of your sites use the same code and replacing it means you have to reconcile any broken code in all of your projects right away, instead of upgrading applications one by one.

Each method has drawbacks and advantages. OpenAvanti recommends following the approach outlined in #2, as this allows you the greatest amount of separation between your code and OpenAvanti, as well as limits the negative impacts on using the same set of OpenAvanti code for all of your applications.

The OpenAvanti Recommendation: Non-distributed Applications

For non-distributed applications (meaning applications that are not freely distributed on the web), OpenAvanti recommends the following directory structure, or something similar:

base/
    pages/
        css/
        images/
        js/
    php/
        openavanti/
        controllers/
        models/
        views/

The base/ directory is the root of your application’s code. OpenAvanti would obviously be stored in the php/openavanti/ folder inside this directory, allowing it to stay separate from all the other code.

All controllers which extend the OpenAvanti controller class should be placed in php/controllers/, and, likewise, all models which extend the OpenAvanti model class should code in php/models/. View files, which contain the code that is displayed to the user, is stored in php/views/. None of this matters if you are not using the MVC architecture to structure your application.

All other miscellaneous classes or extensions of the base OpenAvanti classes could be stored in the php/ directory.

All publicly accessible files, such as your index.php file, images, CSS and JavaScript, should be placed in the pages/ directory, which is broken up above into css/, images/ and js/ directories.

A file in pages/ would likely instantiate classes stored in the php/ directory, and eventually, require view files from the php/views/ directory would be required and displayed to the user.

For this method to work, we will have to set the document root of our site in our webserver as /path/to/www/base/pages, instead of just /path/to/www/base, as we will store all public accessible files one directory higher.

In order for a structure like this to work efficiently, we’ll have to setup an include path, which is described below.

The OpenAvanti Recommendation: Distributed Applications

For distributed applications, our approach above may not work well as the user may not be able to made modifications to the server’s configuration to change where the document root points to. For distributed applications, OpenAvanti recommends something similar to this:

base/
    application/
        openavanti/
        controllers/
        models/
        views/	
    css/
    images/
    js/

The base/ directory is the root of your application’s code. OpenAvanti would be stored in the application/openavanti/ folder inside this directory, allowing it to stay separate from all the other code. It might be worth while to put an empty index.php file in each of these directories under application/ if you cannot properly set indexing to false in your web server.

All controllers which extend the OpenAvanti controller class should be placed in application/controllers/ and, likewise, all models which extend the OpenAvanti model class should code in application/models/. View files, which contain the code that is displayed to the user, is stored in application/views/. None of this matters if you are not using the MVC architecture to structure your application.

All other miscellaneous classes or extensions of the base OpenAvanti classes could be stored in the application/ directory.

All publicly accessible files, such as your index.php file, images, CSS and JavaScript, should be placed in the base/ directory, which is broken up above into css/, images/ and js/ directories.

A file in base/ would likely instantiate classes stored in the application/ directory, and eventually, require view files from the application/views/ directory would be required and displayed to the user.

In order for a structure like this to work efficiently, we’ll have to setup an include path, which is described below.

Setting up Your Include Path

Regardless of how you structure your directories and where you place the OpenAvanti files, you’re going to need to setup your include path to be aware of all the different directories PHP should look for require()d or include()d files.

The biggest benefit of setting up an include path is that instead of doing this:

<?php    
    require( "/var/www/app/php/controllers/class.articlecontroller.php" );
?>

We can do this:

<?php    
    require( "class.articlecontroller.php" );
?>

Because we setup our include path to look in certain directories, PHP will analyze each, in order, and stop at the first file it finds matching the name of the file we’re trying to require.

Using the Non-distributed Applications directory setup defined above, our include path would be setup like this:

<?php	
    $sBasePath = realpath( "../" );
 
    $aIncludePath = explode( PATH_SEPARATOR, get_include_path() );
 
    $aIncludePath[] = "{$sBasePath}/php/openavanti";
    $aIncludePath[] = "{$sBasePath}/php/models";
    $aIncludePath[] = "{$sBasePath}/php/controllers";,
    $aIncludePath[] = "{$sBasePath}/php/views";
    $aIncludePath[] = "{$sBasePath}/php";
    $aIncludePath[] = "{$sBasePath}/pages";
 
    set_include_path( implode( PATH_SEPARATOR, $aIncludePath ) );
?>

Using the Distributed Applications directory setup defined above, our include path would be setup like this:

<?php	
    $sBasePath = realpath( "." );
 
    $aIncludePath = explode( PATH_SEPARATOR, get_include_path() );
 
    $aIncludePath[] = "{$sBasePath}/application/openavanti";
    $aIncludePath[] = "{$sBasePath}/application/models";
    $aIncludePath[] = "{$sBasePath}/application/controllers";
    $aIncludePath[] = "{$sBasePath}/application/views";
    $aIncludePath[] = "{$sBasePath}/application";
 
    set_include_path( implode( PATH_SEPARATOR, $aIncludePath ) );
?>

This code first determines the current working directory of the application. This is your document root, the path to where your public files are stored. We need this to setup absolute paths to our directories.

In the case of Non-distributed applications, we move down one directory to get the base application directory. For Distributed Applications, all of our directories are stored below the document root, so that is sufficient for setting up our include path.

The array we setup is a list of all the directories we want PHP to check when we require() or include() files. We store them in an array to make it easy, clean, and simple to make modifications to.

In the last line, we use PHP’s set_include_path() function to set the PHP include path to ours. We implode the $aIncludePath array into a string and use the PHP define PATH_SEPARATOR as the glue for these array pieces. Normally, the value of PATH_SEPARATOR is a colon (:).

At the end of this code, we’ve altered the include path for PHP to make PHP check all of our directories for files when we do a require() or include().

Installation