dispatch() and routing

dispatch method is used for all routing purposes. Let us look at a basic routing example,

    

    dispatch('say_hello/', 'hi');

    function hi()
    {
        echo 'Hello world!';
    }
    

If we were to load the URL: http://example.com/forum/say_hello, we would get Hello world! as output.

What are Routes?

Routes combine

• an HTTP method
• with an URL matching pattern
• and a callback parameter

So they make the glue between an URL + a HTTP method, and the code provided in a callback controller.

    dispatch('get_something/', 'my_get_function');
    //same as dispatch_get('my_get_function');
    function my_get_function()
    {
        // Show something
        // with the code of this callback controller
    }

    dispatch_post('post_something/', 'my_post_function'); 
    function my_post_function()
    {
        // Create something
    }

    dispatch_put('put_something/', 'my_update_function'); 
    function my_update_function()
    {
        // Update something
    }

    dispatch_delete('delete_something/', 'my_delete_function'); 
    function my_delete_function()
    {
        // Delete something
    }

    dispatch_patch('patch_something/', 'my_patch_function');
    function my_patch_function()
    {
        // Patch something
    }

Routes are matched in the order they are declared. The search is performed with a path given through browser URL:

http://localhost/codoforum/?u=my/path  

or if SEF is enabled,
http://localhost/codoforum/my/path

When PUT,DELETE or PATCH methods are not supported (like in HTML form submision), you can use the _method parameter in POST requests: it will override the POST method.

<form action="{$smarty.const.RURI}my/path" method="post">
    <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
    <p>... your form fields</p>
    <p><input type="submit" value="Update"></p>
</form>

Routing patterns and parameters

Patterns may include named parameters. Associated values of those parameters are available with the params() function.

    dispatch('hello/:name', 'hello');
    function hello()
    {
        $name = params('name');
        return 'Hello $name';
    }

Patterns may also include wildcard parameters. Associated values are available through numeric indexes, in the same order as in the pattern.

    dispatch('writing/*/to/*', 'my_letter');
    function my_letter()
    {
        // Matches /writing/an_email/to/joe
        $type = params(0); # "an_email"
        $name = params(1); # "joe"
        // ...
    }

    dispatch('files/*.*', 'share_files');
    function share_files()
    {
        // matches /files/readme.txt
        $ext = params(1);
        $filename = params(0).".".$ext;
        // ...
    }

Unlike the simple wildcard character *, the double wildcard character ** specifies a string that may contain a /

    dispatch('files/**', 'share_files')
    function share_files()
    {
        // Matches /files/my/own/file.txt
        $filename = params(0); # my/own/file.txt
    }

Pattern may also be a regular expression if it begins with a ^

    dispatch('^/my/own/(\d+)/regexp', 'my_func');
    function my_func()
    {
        // matches /my/own/12/regexp
        $num = params(0);
    }

Wildcard parameters and regular expressions may be named, too.

    dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
    function my_func()
    {
        // Matches /say/hello/to/joe
        $what = params('what');
        $name = params('name');
    }

You can also provide default parameter values that are merged with and overriden by the pattern parameters.

    $options = array('params' => array('firstname'=>'bob'));
    dispatch('hello/:name', 'hello', $options);
    function hello($firstname, $name) # default parameters first
    {
        return 'Hello $firstname $name';
    }

Callback controllers

The callback can be a function, an object method, a static method or a closure. See php documentation to learn more about the callback pseudo-type.

# will call my_hello_function() function
dispatch('hello/', 'my_hello_function');

# Static class method call, MyClass::hello();
dispatch('hello/', array('MyClass', 'hello'));

# Object method call, $obj->hello();
dispatch('hello/', array($obj, 'hello'));

# Static class method call (As of PHP 5.2.3), MyClass::hello();
dispatch('hello/', 'MyClass::hello');

# Using lambda function (As of PHP 5.3.0)
dispatch('hello/', function(){
  return 'Hello World!';
});