F-engine

User guide
User guide

Controllers

Controllers are the heart of your application, as they determine how HTTP requests should be handled.

What is a Controller?

A Controller is simply a class file that is named in a way that can be associated with a URI.

Consider this URI:

example.com/index.php/ blog /

In the above example, F-engine would attempt to find a controller named blog.php and load it.

Let's try it:  Hello World!

Let's create a simple controller so you can see it in action. Using your text editor, create a file called blog.php , and put the following code in it:

Then save the file to your application/controllers/ folder.

Now visit the your site using a URL similar to this:

example.com/index.php/ blog /

If you did it right, you should see Hello World! .

Note: Class names must start with an uppercase letter. In other words, this is valid:

<?php
class Blog extends Controller {

}
?>

This is not valid:

<?php
class blog extends Controller {

}
?>

Also, always make sure your controller extends the parent controller class so that it can inherit all its functions.

Functions

In the above example the function name is index() . The "index" function is always loaded by default. You could also call any other function within your controller remapping function calls.

F-engine is also able to auto detect ajax calls from most common javascript frameworks such as jquery. Ajax requests are auto redirected to ajax() function whenever it is defined. For example:

If you write your own ajax requests instead of using a javascript framework, you can make them compatible with f-engine ajax request detection adding the following code:

xmlHttpRequest.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

Passing URI Segments to your Functions

The segments after controller name will be passed to your function as parameters.

For example, lets say you have a URI like this:

example.com/index.php/ products / shoes / sandals / 123

Your function will be passed URI segments 2,3 and 4 ("shoes","sandals" and "123"):

<?php
class Products extends Controller {

    function index($shoes, $sandals, $id)
    {
        echo $sandals;
        echo $id;
    }
}
?>

Important:  If you are using the URI Routing feature, the segments passed to your function will be the re-routed ones.

Defining a Default Controller

F-engine can be told to load a default controller when a URI is not present, as will be the case when only your site root URL is requested. To specify a default controller, open your application/config/routes.php file and set this variable:

$route['default_controller'] = ' Blog ';

Where Blog is the name of the controller class you want used. If you now load your main index.php file without specifying any URI segments you'll see your Hello World message by default.

Remapping Function Calls

As noted above, the second segment of the URI typically determines which function in the controller gets called. F-engine permits you to override this behavior through the use of the _remap() function:

function _remap()
{
    // Some code here...
}

Important:  If your controller contains a function named _remap() , it will always get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which function is called, allowing you to define your own function routing rules.

The overridden function call (typically the second segment of the URI) will be passed as a parameter the _remap() function:

function _remap( $method )
{
    if ($method == 'some_method')
    {
        $this->$method();
    }
    else
    {
        $this->default_method();
    }
}

Processing Output

F-engine has an output class that takes care of sending your final rendered data to the web browser automatically. More information on this can be found in the Views and Output class pages. In some cases, however, you might want to post-process the finalized data in some way and send it to the browser yourself. F-engine permits you to add a function named _output() to your controller that will receive the finalized output data.

Important:  If your controller contains a function named _output() , it will always be called by the output class instead of echoing the finalized data directly. The first parameter of the function will contain the finalized output.

Here is an example:

function _output($output)
{
    echo $output;
}

Please note that your _output() function will receive the data in its finalized state. Benchmark and memory usage data will be rendered, cache files written (if you have caching enabled), and headers will be sent (if you use that feature) before it is handed off to the _output() function. If you are using this feature the page execution timer and memory usage stats might not be perfectly accurate since they will not take into acccount any further processing you do. For an alternate way to control output before any of the final processing is done, please see the available methods in the Output Class.

Private Functions

In some cases you may want certain functions hidden from public access. To make a function private, simply add an underscore as the name prefix and it will not be served via a URL request. For example, if you were to have a function like this:

function _utility()
{
  // some code
}

Trying to access it via the URL, like this, will not work:

example.com/index.php/ blog / _utility /

Class Constructors

If you intend to use a constructor in any of your Controllers, you MUST place the following line of code in it:

parent::Controller();

The reason this line is necessary is because your local constructor will be overriding the one in the parent controller class so we need to manually call it.

If you are not familiar with constructors, in PHP 4, a constructor is simply a function that has the exact same name as the class:

<?php
class Blog extends Controller {

       function Blog()
       {
             parent::Controller();
       }
}
?>

In PHP 5, constructors use the following syntax:

<?php
class Blog extends Controller {

       function __construct()
       {
             parent::Controller();
       }
}
?>

Constructors are useful if you need to set some default values, or run a default process when your class is instantiated. Constructors can't return a value, but they can do some default work.

Reserved Function Names

Since your controller classes will extend the main application controller you must be careful not to name your functions identically to the ones used by that class, otherwise your local functions will override them. See Reserved Names for a full list.

That's it!

That, in a nutshell, is all there is to know about controllers.

Elapsed time: 0.0047
Memory usage: 0.5MB