2. How it works

The general execution process from start to finish can be summed up in the following steps:

  1. Parse a given URL into a UrlCommand containing the name of a Controller, the name of an Action and zero or more parameters.
  2. Execute the UrlCommand which loads the required Controller class and executes the appropriate Action method within that Controller. This returns a View object.
  3. Attach the View to the GlobalView.
  4. Render the GlobalView.

The bundled index.php gateway script includes a call to Core::boot() which will take care of this entire process for you, but we'll describe the various stages and elements in more detai below so you can gather a better idea of how Buan actually operates.

The UrlCommand

All the functional elements that make up Buan are brought together by the concept of the UrlCommand, which is simply an object representation of a requested URL.

A UrlCommand consists of three key components:

  • A Controller
  • An Action, and
  • Zero or more parameters

The process behind how a UrlCommand is generated from a simple string URL is handled by a URL-parsing routine within the UrlCommand::create() method which is called as follows: 

// Given the URL: http://www.my-domain.net/people/list/bob/full-details
$command = UrlCommand::create('/people/list/bob/full-details');

The default URL-parsing routine

Continuing with our example URL above, the default parsing routine will break it down in the following elements: 

Controller: 'people'
Action: 'list'
Parameters: array(0=>'bob', 1=>'full-details')

Next, it finds a suitable Controller class file; PeopleController.php in this case. The following locations are searched to find this file (the order of which is significant):

  • [app.dir.controllers]
  • [core.dir.controllers]
  • [ext.*.dir.controllers] (all installed extensions)

If the file is found then an instance of that Controller class is created and stored in the UrlCommand.

However, if the file is not found then people is treated as a sub-folder in which a search is carried out for a Controller class file based on the name of the next element in the URL, ie. ListController.php.

This process will continue until either a suitable Controller class has been found or all searches have been exhausted and no Controller class was found. If the latter then Buan will use the special Controller, UnknownController. This Controller is available in [core.dir.controllers], but can be easily overridden by creating your own [app.dir.controllers]/UnknownController.php class.

Writing a custom URL-parsing routine

If you would prefer not to use the default parsing routine described above, then you can very easily write your own function/class-method to handle it exactly as you need. To do this you must register your custom function/class as follows (this would most likely be added to your [app.dir.config]/bootstrap.php file): 

// Function that parses URLs
function myParser($url) {
	// ... parse URL and generate a valid UrlCommand instance ...
	return $urlCommandInstance;
}

// Register the function to override the default behaviour
UrlCommand::registerUrlParser('myParser');

The function (or class method) that you register via UrlCommand::registerUrlParser() must accept a single argument, the URL, and must return a UrlCommand instance which will use an existing, valid Controller class.

Executing the command

Once a valid UrlCommand instance has been created, it can be executed.

Assuming PeopleController.php was found in our example URL, the next step is to execute the Action part of the URI, ie. list. This should simply be a public method in the PeopleController class, but rather than calling the method directly it is actually executed via the Controller::invokeAction() method as follows: 

$c = new PeopleController(array(0=>'bob', 1=>'full-details'));
$view = $c->invokeAction('list');

All Controller methods take a single argument which is an array containing all the parameters that were passed in the URL. This is an integer-indexed array and the order of the parameters within it match the order in which they were passed in the URL. Any other named parameters (ie. those in the query portion of the URL) are not included in this array, but can be accessed as normal from $_GET, $_POST, etc.

Note that all Controller Actions must return a View object (or a class that extends the core View class.)

The '/global-view' command

This is a special command that will result in a View that represents the GlobalView - a kind of wrapper template (see GlobalView for more details.)

Rendering a View to output

The resulting $view object returned by a Controller is attached to the 'action' slot within the GlobalView (a special View which we'll look at later) and finally rendered to output: 

$GView = View::getGlobalView();
$GView->attachViewToSlot($view, 'action');
echo $GView->render();
exit();