Documentation
Class libraries
url
The url library is implemented as a singleton class. It parses the $_GET request and, through calls to its methods, gives access to parsed data such as the language prefix, the requested addon (controller), action (the addon's method that will be called) and any parameters that may specified in the url. It also supports the building of new url addresses to allow redirecting to some other page.
File: tokernel.framework/lib/url.lib.php
url library configuration
The url library parses the $_GET request according to the parameters specified in the configuration file listed bellow
application/config/tokernel.ini
toKernel recognizes URLs formatted in a Search Engine friendly way and doesn't make use of the traditional PHP query string specified after a "?" mark.
A typical toKernel URL would be:
http://www.example.com/en/news/show_article/id/77/view_mode/full
where:
- en is the language prefix
- news is the name of the addon to be invoked
- show_article is the name of the method that will be called within the news addon
- id, 77, view_mode, full are the parameters handled by the show_article method.
Parameters can be parsed in two different modes: Assoc or Each.
You can specify which one to use using the http_params config parameter in tokernel.ini
[HTTP]
; How to parse parameters from url.
;
; Receive parameters by associative mode.
; param_name/param_value
;
; http_params_mode=assoc
;
; Receive each parameter as is.
; param1_value/param2_value
;
; http_params_mode=each
;
http_params_mode=assoc
In Assoc mode, parameters are considered as a list of key, value pairs, while in Each mode, parameters are merely a list of values. In the above example, the url parameters would be parsed as follows in Assoc mode:
id=77
view_mode=full
while the result in Each mode would be:
0=id
1=77
2=view_mode
3=full
The url items and values will be cleaned (i.e. all special characters will be removed) by default. You can change this behavior by setting the auto_clean config parameter to 0 (no cleanup) or 1 (cleanup)
; Clean URL on initialization.
auto_clean_url=1
If your application should support several languages and has pages which have a version for each of these languages, you should set the http_parse_language config parameter to 1.
In this case the url library will try to parse the very first item after the domain name as the language prefix.
If this item is not present in the list of the application supported languages (as specified by the allowed_languages config parameter) the language prefix will be considered missing and the language will revert to the application default language.
; Allow parse language prefix from url.
; For example, example.com/en will be parsed as English
; language by "en" prefix.
http_parse_language=1
; Default application language.
http_default_language=en
; Allowed languages for application.
http_allowed_languages=en|fr|es
Library initialization
The library is one of those base libraries that the framework relies upon. Therefore it is loaded and initialized by the application instance at startup by calling its init() method.
During the application execution, every addon, module or view has access to the library methods via $this->lib->url
Parameter access methods
mixed language_prefix()
Returns the application language prefix. If the application is not multilanguage, i.e. the http_parse_language config parameter is set to 0, this method will return false.
string id_addon()
Returns the name of the requested addon (i.e. the name of the main controller). In the above example, the method would return 'news'.
string action()
Returns the name of the action (i.e. method) within in the addon class.
In the above example, the method would return 'show_article'.
Note: The action's name in the URL matches the name returned by action(), but the actual name of the addon's method is prefixed with 'action_'
mixed params([key])
When called without the key argument, returns an array containing all the parameters specified in the URL or false is there is none. When the method is called with a key argument, it will return the value of the parameter identified by the key or false is the key has no value.
In the above example, if we want to get the value specified for id, we should call:
$id = intval($this->lib->url->params('id'));
which will then return 77.
int params_count()
Returns the number of parameters specified in the URL.
string template()
Returns the name of the template file which will be loaded by default by the application instance. In the above example, this method would return 'news.show_article'
URL methods
These additional methods are defined for accessing the request url or help build a new one.
string base_url()
Returns the base url like:
http://www.example.com/
Base url also can be defined in the configuration file as follows:
; Application base URL (optional).
base_url=/tokernel/
string dynamic_url()
Returns the base url but always parsed from query string
string url([addon] [, action] [, add_parameters] [, remove_parameters])
This method is provided to help building a new url by mixing some of the existing parameters and new ones as defined by the application.
$url = $this->lib->url->url();
This will return the same result as base_url() with the language prefix appended (whether supplied in the original URL or the application's default)
Result: http://www.example.com/en/
$url = $this->lib->url->url(true, true);
Returns the application url with the language prefix and requested addon and action.
Result: http://www.example.com/en/news/show_article/
$new_params = array(
'subject' => 'tokernel',
'last_id' => 99
);
$url = $this->lib->url->url(true, true, $new_params, true);
Returns the application url with the language prefix, requested addon and action and additional parameters supplied.
Result: http://www.example.com/en/news/show_article/subject/tokernel/last_id/99/
If the last argument in the call is defined as false, then the parameters supplied in the request will be merged with the new ones.
$new_params = array(
'subject' => 'tokernel',
'last_id' => 99
);
$remove_params = array('view_mode');
$url = $this->lib->url->url(true, true, $new_params, $remove_params);
This will return the application url with the request's and new parameters merged together. Parameter view_mode will be removed.
Result: http://www.example.com/en/news/show_article/id/77/subject/tokernel/last_id/99/
$url = $this->lib->url->url(true, 'view_all');
This will return url with request's addon name and new view_all action.
Result: http://www.example.com/en/news/view_all/
$new_params = array(
'cat_id' => 61,
'offset' => 2
);
$url = $this->lib->url->url('gallery', 'show_category', $new_params, true);
This will return a newly created url just keeping the base url and discarding all items supplied in the request's URL.
Result: http://www.example.com/en/gallery/show_category/cat_id/61/offset/2