Chapter 6. URLs

Table of Contents

Calling an action
Routing urls
Creating routes
Retrieving route parameters
Building urls with Atomik::url()

Calling an action

Atomik provides a simple url mechanism. Whatever the page is, the url must always point to Atomik script, i.e. index.php

The url should contain a parameter which specify which action to trigger. This parameter can be modified in the configuration (using the “atomik/trigger” key) but its default name is “action”.

The value of the parameter must only contain the action name without any extension. So for example if you have an home.php file in the app/actions directory or/and an home.php file in the app/views directory, you must use “home” as parameter to call this action. Thus, the url should look like http://example.com/index.php?action=home.

For an action to be callable, an action file or a view file must at least exist.

If the action parameter is not found in the query string, Atomik will use the default action defined in its configuration (the “atomik/default_action” key). The default is “index”.

For cleaner and prettier url you can use url rewriting. When using Apache, simply copy the code below into a .htaccess file in the same directory as Atomik's core file.

RewriteEngine on
RewriteRule ^app/plugins/(.+)/assets - [L]
RewriteRule ^app/ - [L,F]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?action=$1 [L,QSA]
			

This code will also prevents access to the app folder from the web but allow access to assets directories provided by plugins.

When using url rewriting, you can access pages by directly appending the name to the base url. Eg: http://example.com/home

Note

Sometimes Atomik cannot detect if url rewriting is activated and Atomik::url() still uses index.php. To prevent this, set the “url_rewriting” configuration key to true.

The action that has been called can be found in the configuration key named “request_uri”. The base url of the website (ie. the path before the root of the site) can be found in the “base_url” key.

Routing urls

Creating routes

It is now a common practice to use pretty urls. This can easily be done using Atomik's router. The router map urls to actions and allows you to extract parameters from these urls. An url and its parameters is called a route.

Routes are defined in the “routes” configuration key. The action must be specified as a parameter named “action”.

Note

You can't set routes using an array as first parameter of Atomik::set(). If not, the array will be dimensionize and the router won't work.

Example 6.1. Simple route

					
Atomik::set('routes', array(
   'user/add' => array(
       'action' => 'user_add'
   )
));
				

As you see, the route is define as the array key and its parameters are defined in the sub array. You can add an unlimited numbers of parameters to the route. There must be at least action parameter for the route to be valid.

The real magic of the routes is the possibility to assign a parameter value with a segment of the uri. This is done by specifying a parameter name prefixed with “:” inside an uri segment (ie. between slashes).

Parameters defined as uri segments can be optional if they are also defined in the parameters list.

Example 6.2. A route with some parameters

					
Atomik::set('routes', array(
   'archives/:year/:month' => array(
       'action' => 'archives',
       'month' => 'all'
   )
));
				

In this route, the month parameter is optional but not the year. Thus, possibles urls are http://example.com/archives/2008 or http://example.com/archives/2008/02. In these case the year parameter will have the “2008” value and the month parameter in the second example will have “02” as value.


Note

Routes are match in reverse order.

Retrieving route parameters

Once the routing process is done, a configuration key named “request” is available. It contains an associative array with parameters and their value.

Example 6.3. A route with some parameters

					
$params = Atomik::get('request');
$year = Atomik::get('request/year');
				

Building urls with Atomik::url()

Directly writing url into your code can lead to problems. When using a layout for example, it is hard to know the relative location of the current view to include stylesheets for example. Some urls also needs lots of concatanation when using parameters and this can make the code less readable.

Atomik::url() tries to resolve those problems by providing three things:

  • Prepends the base url
  • Do not use index.php in the url if url rewriting is enabled (or use it if not)
  • Handles url parameters

The method works best with relative or absolute urls. It can however also works with full urls. In this case, the two first points won't be applied.

Example 6.4. Building simple urls

				
$url = Atomik::url('home'); // /index.php?action=home if no url rewriting or /home otherwise
$url = Atomik::url('/user/dashboard'); // /user/dashboard
$url = Atomik::url('http://example.com'); // http://example.com
			

You can add GET parameters to the url using an array as the second argument.

Example 6.5. Building urls with parameters

				
$url = Atomik::url('archives', array('year' => 2008)); // /index.php?action=archives&year=2008 if no url rewriting or /archives?year=2008 otherwise
$url = Atomik::url('archives?year=2008', array('month' => 02)); // /archives?year=2008&month=02
			

The method also allows you to use embedded parameters. These are parameters in the uri. The name of the parameter must be prepended with “:”.

Example 6.6. Building urls with embedded parameters

				
$url = Atomik::url('archives/:year', array('year' => 2008)); // /index.php?action=archives/2008 if no url rewriting or /archives/2008 otherwise
$url = Atomik::url('archives/:year', array('year' => 2008, 'month' => 02)); // /archives/2008?month=02
			

Finally, when creating urls that point to resources you'll never want them to have the index.php part in them. To prevent that you can use the Atomik::asset() method. It works exactly the same as Atomik::url() but will never use index.php in the url.