Set Up A Friendly Url System With Match - SergiJuanola/Toolbox GitHub Wiki

Learn how to use Toolbox to set up a friendly url system, with seo improvements for your url, using Match,

##Getting started

For the first tutorial, let's download a fresh copy of Toolbox and extract it somewhere in your server. In our example, we will save it next to our public_html/ folder:

.
├── public_html
│   └── index.php
└── toolbox
    ├── class.base.php
    ├── class.brush.php
    └── ...

After that, we will create two files: index.php and .htaccess.

####.htaccess

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php

This file lets any request of a file or directory that doesn't exist, go through index.php.

####index.php

<?php 
require_once '../toolbox/class.toolbox.php';
if(!defined("__DIR__")) define("__DIR__", dirname(__FILE__));

$app = Toolbox::build(array(
    'match'     =>  array(
                        'matchbox'  =>  __DIR__.'/matchbox/'
                    ),
  ));

This is everything you need to use Match. Lets see what really happens:

  1. Require the Toolbox class. By doing such thing, we will have autoload capabilities without breaking other autoload systems (in case you use another library).
  2. Define a __DIR__ constant. This is done because PHP 5.3 defines the __DIR__ constant by default, but 5.2 doesn't. This constant will help us referencing folders, as you will see.
  3. Create an $app using the Toolbox::build() call.
  4. Pass an associative array to Toolbox::build(), where a key is 'match' and references another array with the key 'matchbox'. It is the folder where the controllers are stored. For our purpose, we defined it as __DIR__.'/matchbox/'.

Now that the index.php file has a basic configuration, we can begin preparing rules for Match.

##The Match rule structure

Match works entirely using something we call rules. These rules are what tells Match to go for a web page or another. We can independently define rules for each of the four verbs GET, POST, PUT and DELETE, or a rule that will be triggered in any case.

A really basic example is the following:

<?php 
require_once '../toolbox/class.toolbox.php';
if(!defined("__DIR__")) define("__DIR__", dirname(__FILE__));

$app = Toolbox::build(array(
    'match'     =>  array(
                        'matchbox'  =>  __DIR__.'/matchbox/'
                    ),
  ));


$match = Match::build()
->get('/', 'Home::index')
->fire();

As you see, we are adding some code to the previously created index.php file. We first create a $match instance using Match::build() and start creating rules by writing the next line. Let's disset it a little:

  • ->get: defines the verb. As aforementioned, we have 4 verbs in total, plus a wildcard that works as any of those:

    • ->get
    • ->post
    • ->put
    • ->delete
    • ->matchAny

    The last one is the wildcard, and any rule written inside will match any verb from the above. All of them have the same structure, and make no differences between verbs when defining rules.

  • '/': The first parameter is the uri. This is what will be looked for in the url. In this case, we are only matching our homepage.

  • 'Home::index': The second parameter is the callback. This is the action the current uri triggers. In this case, we are calling an action from HomeController, called index. And that's what you will see in the following section.

You may also see that ->fire() command. That is called once and after all the rules are defined. That is what fires Match and tells it to start looking for a rule.

##The Controller system

Now that you have a rule that checks the home page, you need a controller that handles the callback. Create a folder called matchbox/ (or whatever you defined in the configuration) and create a new file inside, called controller.home.php. This is very important: the name neets to prepend controller. and it needs to be lowercase. Then, the class should be called HomeController, to avoid name repetitions with other plugins or libraries.

<?php 

require_once('../toolbox/class.controller.php');

class HomeController extends Controller {
    public function index()
    {
        echo 'Hello, World!';
    }
}

As you see, we require the parent Controller class, create a class that extends this, and create a method named as we did in the callback, in our case, index(). We echo 'Hello, World!' as an example, but you could do anything you want.

##Today you learned

  1. To create a basic configuration for Match.
  2. To define a rule and a callback to that rule.
  3. To create a Controller that handles that callback.