Handling requests with controllers

Routing requests

The Outlast Framework uses a heavily standardized model-view-controller (MVC) interface for your web apps. This means less flexibility, but it also means that in all cases class and file names will be predictable and they will be where you expect them to be.

When a user requests a page from your application (say, http://www.example.com/user/profile/), the framework will process the url and send the request to the proper controller method.

Standardized routing rules

Instead of setting up complex routing rules and messing with regular expressions, Outlast Framework introduces a standardized way of handling requests. This will ensure that all projects will handle requests in the same, predictable way. If you need a custom route, instead of modifying rules, you just create a controller file and/or method for it.

How exactly are requests handled? Each controller file is actually a class with various methods in it. Public methods of the controller class are routes for your application, so:

http://www.example.com/ -> default.ctl.php / function main()
http://www.example.com/something/ -> default.ctl.php / function something()
http://www.example.com/something/else/ -> default.ctl.php / function something_else()
http://www.example.com/doesnt/exist/ -> default.ctl.php / function __error('doesnt_exist')

You can also create other controller files, and they will also join in handling requests.

http://www.example.com/another/example/ -> another.ctl.php / function example()
http://www.example.com/another/example/with/more/ -> another.ctl.php / function example_with_more()
http://www.example.com/another/example/doesnt/exist/ -> another.ctl.php / function __error('doesnt_exist')

Finally, you can create folders to group controller files:

http://www.example.com/admin/final/ -> admin/final.ctl.php / function main()
http://www.example.com/admin/final/example/ -> admin/final.ctl.php / function example()

Of course you can always use .htaccess to rewrite requests if needed, but this is not recommended. Better to stick to the standards…

Routing request propagation

Routing requests are run in order from more specific to less specific. If the more specific item is not found, Outlast Framework moves on to the next, less specific possibility. For example, here is how the request /admin/whatever/ would be routed:

1. admin.ctl.php / whatever()
2. admin/whatever.ctl.php / main()
3. admin/whatever/default.ctl.php / main()
4. admin/default.ctl.php / whatever()
5. default.ctl.php / admin_whatever()

If it finds one of these methods propogation will stop and only the most specific method will be run. If you add admin/whatever.ctl.php / main() even though you already have admin.ctl.php / whatever(), the first will always be ignored and only the second will ever run.

In addtion, if you add error methods in any of the above controller files, the propagation will stop at that controller and the __error() magic method will be called with the request as a parameter (see below).

Magic routing methods

There are two built-in magic methods for controller classes: __load() and __error(). Their names are pretty suggestive, but here’s what they do:

• __load($request) – __load runs each time any request hits the given controller file. It can be used for setting up sessions, kicking non-admin users, and other ‘global’ features that are valid for each method of the controller.
• __error($request, $parameters) – the __error method runs any time that the controller class is invoked but the proper method cannot be found. This can be used to display a friendly 404 message or to trigger a friendly-url search for specific data. Any parameters passed to the original method will also be passed as the second param of __error (as an array of params).