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:

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

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

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

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

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

'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:

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

framework directory