Documentation

Getting started

Setup guide

This guide is aimed at letting you quickly set up the framework and let you start developing your first application.
It is not intended to explain all the minute details of toKernel PHP framework's configuration nor list all the possible setups and ways of using it. We will rather show you how a typical installation is done and the recommended settings for such a configuration.

Download

Download the latest toKernel stable version from http://www.tokernel.com/download
The archive file name looks like tokernel.1.0.5.tgz

Archive extraction

Under Unix like system extract the tarball archive:

# tar xvzf file.tgz

Under Windows use your favorite archive extractor to unpack the archive to a temporary directory.

The work directory contains two sub-directories: 'application' and 'tokernel.framework'.
The latter 'tokernel.framework' is the framework properly speaking and should be unique on your system, while the former 'application' provides a skeleton for applications making use of the framework.

Typically, you'll have as many instances of the 'application' directory as you have toKernel applications running on your system.

Copy the content of the 'tokernel.framework' directory to a directory of your choice, depending on the administrative good practices in use on your system or organization.

For example, Ubuntu users may like to install the framework in /opt/tokernel while others may prefer /usr/local/lib/tokernel or even ~/tokernel.

Similarly, Windows users may want to install it in C:\Program Files\tokernel or C:\tokernel.

Please note that, while we do not recommend it, it is not required to keep the name of the directory as 'tokernel.framework' and you may rename to whatever you like (and is allowed by your OS).

Copy the content of the 'application' directory to your web site root directory if you want to configure a web application.

Depending on your system and its configuration, this could be:

/var/www
~/public_html
/var/apache/htdocs

under Linux or your IIS site htdoc directory if are under Windows.

Please note, that it is not required to copy the application in the root directory of your web site if you want to use the toKernel framework only for one of the sub-sites of your web site. In this case, copy the content of the 'application' directory to the main directory of the sub-site.

If you want to configure a CLI only application, you can copy the content of the 'application' directory wherever you find it convenient.

Optionally, you can rename the 'application' directory in your new copy of the project directory into whatever you'd like. This could be for example 'my_custom_app'

Now, that the directory structure has been created, a few parameters should be changed to reflect your actual system configuration.
Let's assume the framework has been installed in /usr/local/lib/tokernel and that your web site root directory is /var/www with your 'application' directory located at /var/www/my_custom_app

Open /var/www/index.php in your favorite text editor and change the definition of the 'TK_CUSTOM_DIR' to reflect the name of your 'application' directory. In our example, this has be changed into 'my_custom_app'. Change the line /* Include framework loader */ require("tokernel.framework/tokernel.inc.php"); to reflect the location of the tokernel framework i.e. requite("/usr/local/lib/tokernel/tokernel.inc.php");

Optionally, open /var/www/.htaccess in your favorite editor and change the line

RewriteBase /

to reflect the base url of your web site. In our example, there is nothing to do, but if you have a shared web hosting environment, you should probably change this into something like

RewriteBase /~username/

Configuration

The application configuration is done by editing the 'config/tokernel.ini' file in the application's directory. This file follows the standard .ini file format. In our example, edit /var/www/my_custom_app/config/tokernel.ini

[RUN_MODE]

Application run mode

Set app_mode to 'production' or 'development' depending on your needs.

We strongly recommend to limit 'development' mode only to your development and testing phases. Using this mode for a production application creates a security risk since any error might leak confidential information that could be exploited by attackers.

In 'production' mode, the only message that will be displayed to the user is the message configured in
/usr/local/lib/tokernel/languages/{lng}.ini

[Debug]

Set debug_mode to 1 if you want to receive all debug information at the bottom of the displayed web page for a web application or after output in CLI mode.

We recommend setting debug_mode to 0 (i.e. turn it off) for the production environment.

Set debug_log to 1 to have all debug information output to the debug log file. All log files are located in the application/log directory, i.e. in our example at /var/www/my_custom_app/log

[ERROR_HANDLING]

Set the options in this section to log or display the desired error types.

In development mode, we recommend to set all values to 1, so that you can get warnings for all errors.

[CLI]

Configuration for CLI (Command Line Interface) mode.

If you don't want your application to be called from CLI, you can disable CLI access altogether by just setting 'allow_cli' to 0.

'cli_parse_language=1' directs the CLI parser to parse language prefix from the command line --lng argument.

'cli_default_language=en' sets the default language to English for application in CLI mode.

'cli_allowed_languages=en|ru' indicates the application supports both English and Russian.

If you need to support another language, you need to create a translation file in '/usr/local/lib/tokernel/languages/' named '{lng}.ini' and update the 'cli_allowed_languages' to add this new language. For example 'cli_allowed_languages=en|ru|fr' assuming you have created an fr.ini translation file.

[HTTP]

Configuration for Web (HTTP) mode.

If you don't want your application to be accessible from the Web or through a browser, set 'allow_http' to 0.

Set 'base_url' to reflect the location of the directory where you copied the 'application' folder.

You can ignore this setting if your application resides in the root folder of your web site, but it becomes mandatory if it was installed as a sub-site.

For example, if your application was installed in a shared hosting environment that you access as

http://www.sharedexample.com/~myname

In this case, you should set

base_url=http://www.sharedexample.com/~myname

'http_parse_language': Set this option to 1 if your application should support multiple languages. If this option is set 0, the url will be parsed according to the following template

http://{your_domain}/addon/action/param1/param1_value/param2/param2_value

but if this option value is set to 1 then the url will be parsed as

http://{your_domain}/{language_prefix}/addon/action/param1/param1_value/param2/param2_value

'http_default_language' defines the application default language.

'http_allowed_languages' defines the languages the application supports. (see the explanation of the cli_allowed_languages in the [CLI] section).

'default_callable_addon' defines the addon which will called by default, if the url doesn't specify any specific addon.

'default_callable_action' defines the default action (i.e. addon's method) if the action is not specified in the url.

'redirect_404' defines what page should be displayed in case of a 'page not found' error (404)

If this option is set to 1, the framework will redirect to the home (default) page if the addon or action do not exist. If the option is set to 0, your site's standard error 404 page will be displayed.

'backend.theme', 'frontend.theme' defines the theme for your application frontend and backend.

[CACHING]

Cache configuration for Web (HTTP) mode.

'cache_expiration' defines how long values should to kept in the cache. Any positive integer value sets the cache expiration delay in minutes. Setting this option to -1 will cause the cache to never expire, i.e. the contents of the cache will be kept as long as there is room enough. A value of 0 will disable caching altogether. For example:

cache_expiration=10

will cause the contents of the cache to be marked as invalid after 10 minutes.

Permissions

Change directories permissions (Web mode)

Under Linux, the following directories should be made world writable (chmod 777): /{path_to_web_site}/my_custom_app/cache /{path_to_web_site}/my_custom_app/log /{path_to_web_site}/my_custom_app/session /{path_to_web_site}/my_custom_app/tmp

Directory structure

application instance

Directory Description
application This directory is intented to contain all the files that are specific to your application
application/addons customized addons directory. This is where you should put your application's classes and other layout files such as images and css style sheets used by your addons.
application/cache application's cache files
application/config application's configuration files.
Configuration values is actual for parent application only.
application/hooks Startup and shutdown hooks for application. CLI and web mode hooks are defined in different files.
application/languages This directory is empty by default. If you want to customize toKernel messages for a given language, copy it to this directory and edit the language file contents or add to it.
application/lib Application's library directory. This is where you would put libraries inherited from toKernel or libraries specific to this application.
application/log application's log files
application/session application's session files
application/themes/{some_theme} theme files for application. Each theme directory can contain css, images, templates, views and other files.
application/tmp tmp files (regular directory for temporary files).
.htacess main rewrite rule file for Web mode
index.php this is the bootstrap file for the application.

framework directory

Directory Description
tokernel.framework toKernel framework core files
tokernel.framework/addons framework addons directory
tokernel.framework/config framework default configuration files
tokernel.framework/kernel framework kernel files implementing the core functionality provided by the framework
tokernel.framework/languages default language files
tokernel.framework/lib library files
tokernel.framework/themes default themes