1.3. Post-installation tasks

Application configuration folder

Your gateway script index.php contains [something like] the following line: 

Core::configure('/home/my-app/config');

This is simply telling Buan where to find your application's configuration folder so that it may prepare the environment using information from the files within. In particular it will look for the following files:

  • app.php (required)
    Sets global configuration values in the [app.*] namespace, provides database connection information and defines any required Model relationships.
  • bootstrap.php (optional)
    Contains any custom initialzation-code that you want to execute prior to the dispatch cycle being started.

Let's look at those files in more detail ...

app.php

Global configuration

Your application can use the [app.*] configuration namespace to set whatever variables you wish. However, certain variables must be defined so that Buan knows where to find certain files and knows how to operate on certain data. These variables are listed below and are defined in your app.php file by using the Config::set() class method:

(NOTE: If you're using the bundled app.php then you may not need to specify values for any of these variables as they are already populated with calculated values.)

  • app.command.default
    If no command has been passed via the URL, then the system will default to this command (in the format /controller-name/action-name/param0/param1/.../paramN)
  • app.command.parameter
    Defines the $_REQUEST element in which the URL command will be stored (defaults to do, ie. $_REQUEST['do'])
  • app.command.urlPrefix
    If you want to use "clean" URLs (the default behaviour) then set this to an empty string, otherwise it should be the same as [app.command.parameter].
  • app.dir.controllers
    Absolute path to the folder that contains your Controller classes and subfolders.
  • app.dir.models
    Absolute path to the folder containing your Model classes.
  • app.dir.modelManagers
    Absolute path to the folder containing your ModelManager classes.
  • app.docRoot
    Absolute path to your application's public document root folder.
  • app.domain
    The fully-qualified domain name under which your application is running (eg. www.my-site.com)
  • app.password
    The password used to access the core Buan facilities of your application - change immediately after installation.
  • app.urlRoot
    If you store the entire application within a sub-folder in your domain's document-root, then specify that folder path here (relative to the document-root).
    eg. if application is in "http://www.domain.com/my/app" then urlRoot would be set to "/my/app"

It is strongly recommended that you change the [app.password] setting immediately after installing Buan as it presents a potential security risk to your application. By default, the password is set to admin.

There are also some optional configuration variables that Buan will use where required:

  • app.dir.extensions
    Absolute path to the folder in which you are storing any Buan Extensions.
  • app.dir.ignored
    An array of folder names that will be ignored during any folder-iterations done by the core (eg. .svn, cvs, etc)
  • app.dir.temp
    Absolute path to a temporary folder. If not specified, but is required by any element, then Buan will attempt to find a default path which may be shared with other users on the server.
  • app.extensions
    An array of the names of any Buan Extensions that you want to use in your application. (see Buan Extensions for further information)

Finally there are a few special configuration variables that are created at runtime when you call Core::configure():

  • app.command.requested
    Stores the originally requested command (ie. the value stored in $_REQUEST)
  • app.dir.config
    Absolute path to your configuration folder.

Database connection setup

TODO

Model relationship definitions

TODO

bootstrap.php

Strictly speaking this file is not needed because you could quite easily add any custom initialization routines to the index.php gateway script immediately after Core::configure(...) is called. However, keeping it separately in the configuration folder means you can keep all your environment-initialization logic in one convenient place.

You can put pretty much anything you want in this script. Most common tasks may include:

  • Starting/recovering a session
  • Manipulating [app.command.requested] prior to entering the dispatch routine.
  • Defining custom functions for use elsewhere in the application
  • Defining and registering a custom dispatch routine (see The dispatch routine for more information)
  • Adding custom paths to the BuanAutoLoader classpath