View
234
Download
0
Category
Preview:
Citation preview
8/6/2019 Kohana Doc
1/161
What is Kohana?Kohana is a PHP5 framework that uses the Model View Controller architectural pattern. It aims to
be secure, lightweight, and easy to use.
Features
1. Strict PHP5 OOP. Offers many benefits: visibility protection, automatic class loading,
overloading, interfaces, abstracts, singletons, etc.
2. Community, not company, driven. Kohana is driven by community discussion, ideas, and
code. Kohana developers are from all around the world, each with their own talents. This
allows a rapid and flexible development cycle that can respond to new bugs and requests
within hours.
3. GET, POST, COOKIE, and SESSION arrays all work as expected. Kohana does not
limit your access to global data, but provides XSS filtering and sanity checking of all globaldata.
4. Cascading resources, modules, and inheritance. Controllers, models, libraries, helpers,
and views can be loaded from any location within your system, application, or module paths.
Configuration options are inherited and can by dynamically overwritten by each application.
5. No namespace conflicts. Class suffixes and prefixes are used to prevent namespace
conflicts.
6. Auto loading of classes. All classes in Kohana are automatically loaded by the framework,
and never have to be manually included.
7. API consistency. Classes that require access to different protocols use drivers to keep the
the visible API completely consistent, even when the back end changes.8. Powerful event handler. Kohana events can transparently be: added, replaced, or even
removed completely.
Goals
To be secure means to use best practices regarding security, at all times:
Kohana comes with built in XSS protection, and can also use HTMLPurfier as an XSS filter.
All data inserted into the database is escaped using database specific functions, like
mysql_real_escape_string, to protect against SQL injection attacks. magic quotesare
disabled by Kohana.
All POST, GET, and COOKIE data is sanitized to prevent malicious behavior.
To be lightweight means to provide the highest amount of flexibility in the most efficient manner:
Kohana uses convention over configuration as much as possible.
Sane defaults and highly optimized environment detection routines allow Kohana to run in
almost any PHP5 environment.
Loose coupling is used to always load the minimum number of files, reducing resource
usage.
A clean API and using native functions whenever possible makes Kohana one of the fastest
PHP5 frameworks available.
To be easy to use means to provide understandable API and usage documentation, based on
http://htmlpurifier.org/http://php.net/mysql_real_escape_stringhttp://en.wikipedia.org/wiki/SQL_injectionhttp://php.net/magic_quoteshttp://php.net/magic_quoteshttp://en.wikipedia.org/wiki/Convention_over_Configurationhttp://en.wikipedia.org/wiki/Loose_coupling#Loose_coupling_in_computinghttp://php.net/mysql_real_escape_stringhttp://en.wikipedia.org/wiki/SQL_injectionhttp://php.net/magic_quoteshttp://en.wikipedia.org/wiki/Convention_over_Configurationhttp://en.wikipedia.org/wiki/Loose_coupling#Loose_coupling_in_computinghttp://htmlpurifier.org/8/6/2019 Kohana Doc
2/161
community feedback.
MVC
Kohana uses the Model View Controller architectural pattern. This keeps application logic separate
from the presentation and allows for cleaner and easier to work with code.
In Kohana this means:
A Model represents a data structure, usually this is a table in a database.
A View contains presentation code such as HTML, CSS and JavaScript.
A Controller contains the page logic to tie everything together and generate the page the
user sees.
Features Highly secure Extremely lightweight
Short learning curve
Uses the MVC pattern
100% UTF 8 compatible
Loosely coupled architecture
Extremely easy to extend
Technology Strict PHP5 OOP
Simple database abstraction using SQL helpers
Multiple session drivers (native, database, and cookie)
Powerful event handler allows small modifications dynamically
Originally based on CodeIgniter
CreditsMost of the Kohana source code is written by the Kohana Team. There are a few notable credits,
however.
CodeIgniter
Kohana was originally a fork ofCodeIgniter (CI), which is an open source product of EllisLab.
There are still many similarities between CI and Kohana, particularly in naming conventions and
filesystem design, but all of the code is either new or completely rewritten.
CodeIgniter is 2006 EllisLab, Inc.
phputf8All of the Kohana UTF 8 functions are ported from the phputf8 project.
http://en.wikipedia.org/wiki/Model-View-Controllerhttp://codeigniter.com/http://codeigniter.com/http://ellislab.com/http://codeigniter.com/user_guide/license.htmlhttp://phputf8.sourceforge.net/http://en.wikipedia.org/wiki/Model-View-Controllerhttp://codeigniter.com/http://ellislab.com/http://codeigniter.com/user_guide/license.htmlhttp://phputf8.sourceforge.net/8/6/2019 Kohana Doc
3/161
phputf8 is 2005 Harry Fuecks.
Popoon
The default XSS filter used by Kohana was originally created byChristian Stocker for the popoon
framework. The original file is calledexternalinput.php.
popoon is 2001 2006 Bitflux GmbH
HTML Purifier
The alternative XSS filter used by Kohana is HTML Purifier. This is an optional download.
HTML Purifier is 2006 2007 Edward Z. Yang
SwiftMailer
The recommended way to send emails in Kohana is usingSwiftMailer. This is an optional
download.
SwiftMailer is Chris Corbyn
PHP Markdown
Markdown is a simple text to HTML formatting tool. Kohana includes PHP Markdown as an
optional download.
PHP Markdown is 2006 Michel Fortin
Those who cannot remember the past are condemned to repeat it.George Santayana
HistoryThe history of Kohana is told backwards, because we are looking forward.
Kohana 2.1.x
February 7, 2008 Release of Kohana 2.1.1
February 5, 2008 Release of Kohana 2.1
Kohana 2.0
November 2007
Kohana version 2.0 is released. PHP5 based. New fully OOP framework, no legacy code, includes
modules, built on the cascading resources concept.
The Good Old Days
September October 2007
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txthttp://www.liip.ch/http://www.liip.ch/http://www.popoon.org/http://svn.bitflux.ch/repos/public/popoon/trunk/classes/externalinput.phphttp://svn.bitflux.ch/repos/public/popoon/trunk/classes/externalinput.phphttp://svn.bitflux.ch/repos/public/popoon/trunk/LICENSEhttp://htmlpurifier.org/http://htmlpurifier.org/svnroot/htmlpurifier/trunk/LICENSEhttp://www.swiftmailer.org/http://www.swiftmailer.org/http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/trunk/php4/LICENSEhttp://en.wikipedia.org/wiki/Markdownhttp://michelf.com/projects/php-markdownhttp://michelf.com/projects/php-markdown/licensehttp://en.wikiquote.org/wiki/George_Santayanahttp://en.wikiquote.org/wiki/George_Santayanahttp://www.gnu.org/licenses/old-licenses/lgpl-2.1.txthttp://www.liip.ch/http://www.popoon.org/http://svn.bitflux.ch/repos/public/popoon/trunk/classes/externalinput.phphttp://svn.bitflux.ch/repos/public/popoon/trunk/LICENSEhttp://htmlpurifier.org/http://htmlpurifier.org/svnroot/htmlpurifier/trunk/LICENSEhttp://www.swiftmailer.org/http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/trunk/php4/LICENSEhttp://en.wikipedia.org/wiki/Markdownhttp://michelf.com/projects/php-markdownhttp://michelf.com/projects/php-markdown/licensehttp://en.wikiquote.org/wiki/George_Santayana8/6/2019 Kohana Doc
4/161
We get a BDFL, decision to go PHP5 only, new life, new goals. Almost total rewrite undertaken by
developers. (All three of them)
The Worst of Times
August 2007. Our Project leader goes walkabout, not much happens.
Kohana 1.0
June July 2007 Kohana is re released as version 1.0, without documentation.
Lots of ideas and discussions on the way forward,
Kohana
June 2007.
A new Name, forum, Trac.
In The Beginning
BlueFlame, a community fork of CodeIgniter is released.
Reactions and responses. The fork splits.
May 31 2007 BlueFlame announced
Before The BeginningUp until May 2007
The founding members of Kohana are from the Codeigniter community.
Our initial happiness, and later unhappiness, with CI.
Basic RequirementsKohana will run in almost any environment with minimal configuration. There are a few minimum
server requirements:
1. Server with Unicode support
2. PHP version >= 5.1.3
3. An HTTP server. Kohana is known to work with: Apache 1.3+, Apache 2.0+, lighttpd, and
MS IIS
Optionally, if you wish to use a database with Kohana, you will need a database server. There are
database drivers for MySQL andPostgreSQL, with addition drivers planned.
Required Extensions
1. PCRE must be compiled with enable-utf8 and enable-unicode-propertiesfor UTF 8 functions to work properly.
http://codeigniter.com/forums/viewthread/53347/http://unicode.org/http://docs.kohanaphp.com/libraries/databasehttp://www.mysql.com/http://www.postgresql.org/http://www.postgresql.org/http://php.net/pcrehttp://codeigniter.com/forums/viewthread/53347/http://unicode.org/http://docs.kohanaphp.com/libraries/databasehttp://www.mysql.com/http://www.postgresql.org/http://php.net/pcre8/6/2019 Kohana Doc
5/161
2. iconv is required for UTF 8 transliteration.
3. mcrypt is required for encryption.
4. SPL is required for several core libraries.1)
Recommended Extensions
1. mbstring will dramatically speed up Kohana's UTF 8 functions. However, note that the
mbstring extension must not be overloading PHP's native string functions!
Install KohanaKohana is installed in several easy steps:
1. Download a copy of Kohana.
2. Unzip the package you downloaded. This should create a kohana directory.3. Upload the Kohana files to your webserver, placing index.php in the directory that you
would like Kohana accessible from.
4. Edit the global configuration file application/config/config.php5. Make the application/logs directory writeable. Chmod to 666.6. Make the application/cache directory writeable if you use the cache library. Chmod
to 666.
7. Test your installation by opening the URL you set as the base_url in your favoritebrowser
If you see the Welcome page, your Kohana installation is complete!
Removing index.php from URL'sIf you want really clean URL's and therefore remove the index.php in each URL this is possible.
Tutorial Remove index.php for Apache webserver
Additional Configuration
You can provide your installation with additional configuration by copying files from the system/config directory to the application/config directory. For example if you want toconfigure a database connection, you can copy over system/config/database.php toapplication/config/database.php and edit the database connection details.
After installationAfter installation you're ready to build your first web application with Kohana. If you're new to
Kohana you should first read all articles in the user guide under the 'General' section.
Experiencing Problems?
If you were not able to view the Kohana Welcome page on your server after installing, please readtheTroubleshooting page of the user guide, visit the Kohana Wiki, or ask for assistance in the
community forums.
http://php.net/iconvhttp://php.net/mcrypthttp://php.net/splhttp://docs.kohanaphp.com/installation/requirements#fn__1http://docs.kohanaphp.com/installation/requirements#fn__1http://php.net/mbstringhttp://kohanaphp.com/download.htmlhttp://docs.kohanaphp.com/general/configurationhttp://kohanaphp.com/tutorials/remove_index.htmlhttp://docs.kohanaphp.com/libraries/database/configurationhttp://docs.kohanaphp.com/libraries/database/configurationhttp://docs.kohanaphp.com/general/troubleshootinghttp://docs.kohanaphp.com/general/troubleshootinghttp://trac.kohanaphp.com/wikihttp://forum.kohanaphp.com/http://php.net/iconvhttp://php.net/mcrypthttp://php.net/splhttp://docs.kohanaphp.com/installation/requirements#fn__1http://php.net/mbstringhttp://kohanaphp.com/download.htmlhttp://docs.kohanaphp.com/general/configurationhttp://kohanaphp.com/tutorials/remove_index.htmlhttp://docs.kohanaphp.com/libraries/database/configurationhttp://docs.kohanaphp.com/general/troubleshootinghttp://trac.kohanaphp.com/wikihttp://forum.kohanaphp.com/8/6/2019 Kohana Doc
6/161
[moveTo: Troubleshooting] The Kohana Team tries to make sure that Kohana is as free from bugs as
possible. If you have found a bug, please report it.
For Experienced Users
To use a multi site Kohana install, simply follow these steps.
1. Download a copy of Kohana.
2. Put the system folder somewhere on your server, preferably outside of your webserver'sdocument root.
3. Delete the system folder in your current application.4. For your application's index.php file, change the $kohana_system variable to the
relative or absolute path of where you put the system folder.5. You can now point all of your applications to this one system folder for easy upgrades. This
makes your life a whole lot easier when you have 10+ kohana sites on your server.
Moving system and application directory out of webroot
'webroot' is defined as the top level directory to which a webserver will allow public access. A
correctly configured server will not allow public access to files or directories above webroot in the
directory tree.
It is considered a good security practice to move application, system and modules out ofthe webroot, to prevent potential public access, should PHP be disabled, or your webserver is
compromised. Kohana enables you to place the index.php in the webroot, and all other files outside
of it. Static content, such as stylesheet, image and javascript files, are typically placed within
webroot.In a few steps this can be accomplished
1. Move the directories out of the webroot but leave index.php in
2. Open index.php file in an editor
3. Set the variable $kohana_application to the application directory you're using (must
contain config/config.php file)4. Set the variable $kohana_system to the system directory you're using
Note that moving the system directory out of webroot, also makes it more easily accessible bymultiple Kohana applications. So you can use the same system for multiple applications. This
allows for easy upgrades. Simply refer to the same system in the $kohana_system in applicationA, B etc.
Upgrading 2.1 to 2.2
2.0 to 2.1
Basic InstructionsThese instructions assume that you have not edited your system folder in any way. If you have then
http://trac.kohanaphp.com/newtickethttp://kohanaphp.com/download.htmlhttp://docs.kohanaphp.com/installation/upgrading/2.2http://docs.kohanaphp.com/installation/upgrading/2.1http://trac.kohanaphp.com/newtickethttp://kohanaphp.com/download.htmlhttp://docs.kohanaphp.com/installation/upgrading/2.2http://docs.kohanaphp.com/installation/upgrading/2.18/6/2019 Kohana Doc
7/161
8/6/2019 Kohana Doc
8/161
show_errors has been removed.
Helpers
Helpers must be renamed from helper_name to helper_name_Core if they need tobe extended.
The parameter to add index.php from the URL in html helpers now defaults to false, itneeds to be specified as TRUE if you require it.
Validation
trim, md5, sha1 Validation rules must now be preceded by = (e.g. '=trim').
Validation rule 'regex' must now specify the delimiter.
Database
join($table, $cond, $type) has changed to join($table, $key,$value, $type).
$querynum_rows() has been removed. Use count(query) instead.
Deprecated stuff
Use http_build_query() instead ofhtml::query_string(). Use $thispaginationsql_offset instead of$thispaginationsql_offset().
Use $thispaginationsql_limit instead of$thispaginationsql_limit().
TroubleshootingProgramming is art? So is debugging! A few tips to keep your code bug free and how Kohana can
help.
See what you're doing. Kohana makes this one easy:
Throw variables at Kohana::debug().
Turn on the Profiler to see global variables and the executed queries. Eliminate possible causes of the bug. Isolate the problem.
Check the Kohana log files.
If your using MySQL turning on query logging will help you understand what queries
Kohana is running on your database.
Can't figure things out on your own?
Post your problem in the Kohana Forum (after having searched first, of course).
Drop in at #kohana on irc.freenode.net
Deploying Kohana to Production:Here are a few items you should keep in mind before deploying your Kohana application to a
http://docs.kohanaphp.com/core/kohana#debughttp://docs.kohanaphp.com/core/kohana#debughttp://docs.kohanaphp.com/libraries/profilerhttp://docs.kohanaphp.com/core/loghttp://www.howtogeek.com/howto/database/monitor-all-sql-queries-in-mysql/http://forum.kohanaphp.com/http://forum.kohanaphp.com/index.php?action=searchhttp://docs.kohanaphp.com/core/kohana#debughttp://docs.kohanaphp.com/libraries/profilerhttp://docs.kohanaphp.com/core/loghttp://www.howtogeek.com/howto/database/monitor-all-sql-queries-in-mysql/http://forum.kohanaphp.com/http://forum.kohanaphp.com/index.php?action=search8/6/2019 Kohana Doc
9/161
production environment.
1. Remove the various demo and example controllers
Kohana bundles a various demos and example controllers to help users when getting started. Here
are a few that should be removed:
application/controllers/examples.php application/controllers/welcome.php (if it is not used) modules/auth/controllers/auth.php (if enabled in $config['modules']) modules/forge/controllers/forge_demo.php (if enabled in
$config['modules'])
2. Modify your configuration files
Kohana provides various default configuration files in the system/config directory. Since
Kohana utilizes a cascading file system, you have the option to either utilize the defaultconfiguration file versions or override these files with your own custom versions by creating a copy
in the application/config directory.
Modify your application/config.php:
change $config['site_domain'] from your development setting to the productiondomain.
set $config['display_errors'] = FALSE; to disable error messages from beingdisplayed. You can still check error messages in your log file. Check your settings in
config/log.php to be sure.
You should always try to create custom versions of the following files: system/config/routes.php set your $config['_default'] to your default
controller
system/config/encryption.php change the default $config['key'] modules/auth/config/auth.php change the default salt offsets in$config['salt_pattern'](if you use the Auth module)
system/config/cookie.php set your $config['domain'] system/config/session.php set or verify $config['driver'],$config['name'], $config['encryption'], $config['expiration']
You should also consider creating custom versions of the following files:
system/config/database.php configure your custom database connections (ifrequired)
system/config/log.php set your $config['threshold'] = 1;. This setsyour log threshold to a suitable level for production. Higher threshold levels will log less
critical notices and information, but can slow down your application.
3. Move Kohana core directories outside of the document root
If your host does not allow this structure, use an .htaccess file to protect the core directories.
Although this is an optional step and not required by Kohana, it is considered a good securitypractice to place as few files as possible in your public web server document root directory. Since
most web hosts give you access to at least one level above the web server document root, this should
http://docs.kohanaphp.com/general/filesystemhttp://kohanaphp.com/tutorials/remove_index.htmlhttp://docs.kohanaphp.com/general/filesystemhttp://kohanaphp.com/tutorials/remove_index.html8/6/2019 Kohana Doc
10/161
not be a problem.
Moving your core Kohana directories also gives you the ability to utilize one central Kohana
codebase on your server that can be shared by multiple websites. You could also create a set of
common modules used across all of your web sites.
To accomplish this in Kohana, do the following:
1. move your Kohana system, application, and modules directories at least one levelabove your document root directory (typically public_html or www).
2. modify the following lines in your index.php file: $kohana_application = '../application'; $kohana_modules = '../modules'; $kohana_system = '../system';
Note: This example assumes one level above public_html, however, you can use relative orabsolute directories when specifying directory locations.
Your final directory structure will look similar to this:
yourdomain_root_directory+- application+- system+- modules+- public_html (web server document root)| - index.php| - .htaccess
Removing index.php From URLs
Removing the index.php from your website URLs look better, and can help with SEO.Note: This tutorial only focuses on Apache, but can be adapted for other HTTP servers.
.htaccess
We should start out by reminding you that in programming and computing there is always more than
one way to accomplish the same job. The same goes for this particular task and, as is always the
case, each has its own pros and cons. Let's look at a few to help you decide which is best for your
situation.
First, you will need to create a .htaccess document to enable URL rewriting:
# Turn on URL rewritingRewriteEngineOn
# Put your installation directory here:# If your URL is www.example.com/, use /# If your URL is www.example.com/kohana/, use /kohana/RewriteBase /
# Do not enable rewriting for files or directories that existRewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# For reuests that are not actual files or directories,
8/6/2019 Kohana Doc
11/161
# Rewrite to index.php/URLRewriteRule ^(.*)$ index.php/$1[PT,L]
This example is quite dynamic in that you can add files and directories to your document root as you
desire and you'll never need to modify the rewrite rules. Any files and directories that exist under
your document root will be served. If a request is made for a non existant file or directory (which is
really what the index.php less Kohana URLs are), the request is rewritten to be routed through
index.php transparently. If it can be routed by Kohana, the page is served. Finally, if it wasn't a
request for an existing file or directory and could not be routed by Kohana, a Kohana error page (ex:
404) is displayed. So you not only have dynamic rewrite rules, but you get consistency in your error
pages site wide.
However, this approach does not protect your more sensitive an unintended PHP files against access.
So someone could enter, for example, http://www.example.com/application/views/and get a list of all your view files. Ideally, you should never have your system or application
directories, or any other files you do not want accessed, under your document root. But some servers
are setup such that your access to the server is restricted to document root and you have no choice.Read "Moving system and application directory out of webroot" at
http://doc.kohanaphp.com/installationto learn how to move system/ and application/ out ofyour document root. If you find that you do not have proper access on your server to change your
file system setup, continue on in this tutorial for other options.
.htaccess
Let's protect against direct access to these files:
# Turn on URL rewritingRewriteEngineOn
# Put your installation directory here:# If your URL is www.example.com/kohana/, use /kohana/# If your URL is www.example.com/, use /RewriteBase /kohana/
# Protect application and system files from being viewedRewriteCond $1 ^(application|system)
# Rewrite to index.php/access_denied/URL
RewriteRule ^(.*)$ index.php/access_denied/$1[PT,L]
# Do not enable rewriting for other files that existRewriteCond %{REQUEST_FILENAME} !-fRewriteCond %{REQUEST_FILENAME} !-d
# Rewrite to index.php/URLRewriteRule ^(.*)$ index.php/$1[PT,L]
controllers/access_denied.phpBecause we are rewriting the URL to index.php/access_denied/, we will need aController to handle these URLs. Let's create one now:
http://doc.kohanaphp.com/installationhttp://doc.kohanaphp.com/installationhttp://doc.kohanaphp.com/installationhttp://doc.kohanaphp.com/installationhttp://doc.kohanaphp.com/installation8/6/2019 Kohana Doc
12/161
8/6/2019 Kohana Doc
13/161
RewriteCond $1 ^(index\.php|robots\.txt|favicon\.ico|images|js|css)
# No rewritingRewriteRule ^(.*)$ - [PT,L]
# Rewrite all other URLs to index.php/URLRewriteRule ^(.*)$ index.php/$1[PT,L]
Now we are really done. You can change the allowed files and directories to whatever your own,
specific needs are.
Note: Don't feel like you have to use the most secure solution, or any of these solutions. Choose the
.htaccess file that best suits your needs. Each of the examples here will work better for somesituations than others. If you want more information about mod_rewrite, check the Apache
Documentation.
MigrationUsers of Kohana version 1.x (Blueflame) or CodeIgniter 1.x migrating to Kohana 2.0 can follow
these steps to migrate their application.
Installation
Starting with a fresh Kohana install, delete application folder, and copy your existing
application folder to the same location.
Configuration
Remove your old config folder.
1. Copy the application/config directory from Kohana 2.x toapplication/config
2. Edit application/config/config.php, the main configuration files for yourapplication
3. Review theUser Guide: Configuration page
Logging
The logs directory needs to be writable by the webserver or you can turn logging off.
Class Names
Rename all your controllers to {NAME}_Controller. For example, if your old controller wasPage, make it Page_Controller.
Make your Controller contructors PHP5 if needed:1. function __construct() instead offunction Page()2. parent::__construct() instead ofparent::Controller()
http://httpd.apache.org/docs/2.0/mod/mod_rewrite.htmlhttp://httpd.apache.org/docs/2.0/mod/mod_rewrite.htmlhttp://httpd.apache.org/docs/2.0/mod/mod_rewrite.htmlhttp://docs.kohanaphp.com/general/configurationhttp://docs.kohanaphp.com/general/configurationhttp://httpd.apache.org/docs/2.0/mod/mod_rewrite.htmlhttp://httpd.apache.org/docs/2.0/mod/mod_rewrite.htmlhttp://docs.kohanaphp.com/general/configuration8/6/2019 Kohana Doc
14/161
3. Note: This also applies to Models!
Rename all your models to {NAME}_Model
1. For example, if your old model was PageModel, make it Page_Model2. Change all your model loads to just model name: $thisloadmodel('page')3. If you add a __construct() function, be sure to call parent::__construct()
Libraries
Base Controllers
If you have a base controller for your application (in the libraries folder) your will need to:
1. Change the MY_Controller extends Controller to Controller extendsController_Core
2. Change references to MY_Controller in your controllers to Controller
3. Use the PHP5 syntax for the constructor in your base controller
URI
The CI function uri_to_assoc($offset) becomes segment_array($offset,$associative) with $associative set to TRUE.
Other
Class names need to have _Core appended to them and be capitalized. The file names should alsohave the same caps as the class name (without the
core).
References to those classes need to be capitalized to match the library calls (without the core).
$thisload is deprecated. Kohana uses auto loading so you can instantiate an object (e.g. newView()) without including the class first.
Helpers
Change all your helper calls to the new syntax: helper::function()
1. Example: html::anchor() instead ofanchor()
2. Example: url::base instead ofbase_url()3. Example: form::open() instead ofform_open()4. The default helpers are available in system/helpers
If you have custom helpers they need to be changed. Assuming your helper file is foo.php:
1. wrap all the functions in the file in class foo { }2. prepend public static in front of all the function names
Calls are now made via foo::function().
Note also that the CodeIgniter helpers and libraries typically have this line at the top of the script:
8/6/2019 Kohana Doc
15/161
change it to the following to work in Kohana:
for
In the above example, a View object, $visits, was used as a string. This syntax is encouragedbecause it is very short and readable when mixed with HTML.
Models
There is a important note, in CI you can use the $this in the model and you have the same libraries
as your controller, in kohana only the db library is loaded on a model. If you need more libraries you
have two options:
// Create a new object with the library$uri = new Uri;
$value = $uri->segment(3);// Can not use $this->uri->segment(3) as used in CI// Use the instance of your controller$value = Kohana::instance()->uri->segment(3);
http://www.php.net/arrayhttp://www.php.net/arrayhttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/arrayhttp://www.php.net/arrayhttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echo8/6/2019 Kohana Doc
16/161
8/6/2019 Kohana Doc
17/161
8/6/2019 Kohana Doc
18/161
Kohana Filesystem
File types
Strictly from Kohana's interpretation of MVC Lh (MVC Libraries helpers):
Models are used to represent a specific piece of data, such as a database row in a specific
table, or an HTML form.
Views as used as data to HTML rendering layers.
Controllers are used as the entry point, and handle how a URI is converted into an
application.
Libraries are used for as a tool that operate on some form of pre existing data, either in the
form of an array (e.g.,Session, Validation, Input) or some other data structure, such as ORM
(database table) or Archive (filesystem).
Helpers are used for simple, repetitive tasks, such as creating HTML tags, making a URI
into a URL, or validating an email address.
In addition, Kohana adds the following supporting structure:
Configuration files, simple static arrays that are accessed by convention (file.key)
Language (i18n) files, access the same as config (file.key)
Hooks, which can be used to hook into Kohana during very early processes
The Basics
First of all you should get acquainted with the directory structure of a default Kohana installation.
Once you have unpacked it you will see this (note: the contents of your modules directory will vary
according to the options you select on the download page):
root+- application| +- cache| +- config| +- controllers| +- helpers| +- hooks| +- libraries| +- logs
| +- models| +- views|+- modules| +- media| +- config| +- controllers| +- helpers| +- libraries| +- .....+- system| +- config| +- controllers
| +- core| +- helpers| +- i18n| +- libraries
http://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/validationhttp://docs.kohanaphp.com/libraries/inputhttp://docs.kohanaphp.com/libraries/ormhttp://docs.kohanaphp.com/libraries/archivehttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/validationhttp://docs.kohanaphp.com/libraries/inputhttp://docs.kohanaphp.com/libraries/ormhttp://docs.kohanaphp.com/libraries/archive8/6/2019 Kohana Doc
19/161
| +- models| +- vendor| +- views|+- index.php
You will notice that a lot of the directories in the application and system directories are
exactly the same. This is because Kohana has a cascading filesystem.
Cascading
The Kohana filesystem is made up of a single directory structure that is mirrored in all directories
along what we call the include path, which goes as follows:
application > modules > system
Files that are in directories higher up the include path order take precedence over files of the same
name lower down the order.
For example, if you have a viewfile called layout.php in the application/viewsandsystem/views directories, the one in application will be returned when layout.php issearched for as it is highest in the include path order. If you then delete that file from
application/views, the one in system/views will be returned when searched for.
See the cascading filesystem in action.
Modular
The Kohana filesystem is also modular. This means that custom directories can be inserted along
the include path to be scanned when a file is searched for.
See Modules on how to set these up.
The application and system directories can be thought of as hardcoded modules. They aretreated no differently from regular modules apart from the exceptions listed below.
Exceptions
There are 2 main exceptions in the filesystem:
config.phpMUST reside in the application/config directory. It will not be read if itexists within a module or the system directory. The reason for this is that it contains themodules setting which must be read before all others so the framework knows where the rest ofthe config files are along the include path.
The core files as part ofsystem/core are also not cascading. They are hardcoded into theKohana startup procedures and will not be overridden by files higher up the include path.
Configuration and i18n Files
These files are special as their content entries are merged when multiple files of the same name are
found along the include path. Entries in files greater up the order still override those of which are infiles lower down.
http://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/general/viewshttp://en.wikipedia.org/wiki/Image:Kohana-modules.pnghttp://docs.kohanaphp.com/general/moduleshttp://docs.kohanaphp.com/general/viewshttp://en.wikipedia.org/wiki/Image:Kohana-modules.pnghttp://docs.kohanaphp.com/general/modules8/6/2019 Kohana Doc
20/161
See Configuration and Internationalization for more information on this.
Built in directories
cache
By default, theCache library uses this directory to store its caches when using the File driver. It
should also be where you store any custom cached data from your application.
config
All configuration files that are read by theConfig classmust be stored here.
controllers
All controllersto be directed to by the router must go in here.
helpers
See Helpers.
hooks
See Hooks.
i18n
Language files read by Kohana::lang() are stored here. They are split up into sub directories using
the country code and locale as the name. See Internationalization .
libraries
See Libraries.
logs
By default, log files generated by the Log classare stored in the application/logs directory.
models
See Models.
vendor
3rd party libraries and scripts that are not integrated into Kohana should be stored here. See
Librariesfor more information.
views
See Views.
http://docs.kohanaphp.com/general/configurationhttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/libraries/cachehttp://docs.kohanaphp.com/libraries/cachehttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/general/controllershttp://docs.kohanaphp.com/general/controllershttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/general/helpershttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/core/kohana#kohanalanghttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/general/librarieshttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/general/modelshttp://docs.kohanaphp.com/general/librarieshttp://docs.kohanaphp.com/general/librarieshttp://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/general/configurationhttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/libraries/cachehttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/general/controllershttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/general/helpershttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/core/kohana#kohanalanghttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/general/librarieshttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/general/modelshttp://docs.kohanaphp.com/general/librarieshttp://docs.kohanaphp.com/general/views8/6/2019 Kohana Doc
21/161
ConfigurationInformation on retrieving and setting configuration items can be found on theconfig page.
Structure of config files
Configuration files contain an array named $config. Keys of this array are the actual configuration
items e.g.
Example
$config['site_domain'] = 'localhost/';
File structure of config files
The file structure of config files follows Kohana's file structure.
application > modules > system
Meaning that configuration files in the application directory take precedence over those in modules
take precedence over those in the system directory. The one exception is config.php which ishardcoded into the application/config directory and cannot be moved elsewhere.
config.php
Config.phpis hardcoded into Kohana, meaning it has to be in the application/config
directory./** Options:* site_domain - domain and installation directory* site_protocol - protocol used to access the site, usually HTTP* index_page - name of the front controller, can be removed with URL
rewriting* url_suffix - an extension that will be added to all generated URLs* allow_config_set - enable or disable setting of Config items* global_xss_filtering - enable or disable XSS attack filtering on all user
input* render_stats - render the statistics information in the final page
output* extension_prefix - filename prefix for library extensions* modules - extra Kohana resource paths, see * autoload - libraries and models to be loaded with the controller*/
Configuration files
cache.php
Sets the cache driver, cache lifetime and garbage collection. See for more information the Cachelibrary.
http://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/general/configuration/confighttp://docs.kohanaphp.com/general/configuration/confighttp://docs.kohanaphp.com/libraries/cachehttp://docs.kohanaphp.com/core/confighttp://docs.kohanaphp.com/general/configuration/confighttp://docs.kohanaphp.com/libraries/cache8/6/2019 Kohana Doc
22/161
cookie.php
Sets defaults for cookies. See for more information the Cookie helper.
database.php
Sets database connection settings. Multiple configurations are possbile. See the database
configuration page.
hooks.php
Enable or disable hooks. See Hooks page.
locale.php
Sets the locale and timezone of an application. See Internationalization page.
log.phpSets the logging threshold. See the Logpage.
mimes.php
Sets the available mime types. (See the validation/upload page?)
pagination.php
Sets pagination settings. See the Pagination page.
payment.php
Sets payment settings.
profiler.php
Sets the information the profiler should show. See the Profiler page.
routes.php
Sets the routes Kohana should use. Includes _default and _allowed. See Routing
session.php
Sets session settings including the session driver. See Session.
upload.php
Sets upload directory.
user_agents.php
Sets available user agents including robots and mobile browsers. See User Agent
http://docs.kohanaphp.com/helpers/cookiehttp://docs.kohanaphp.com/libraries/database/configurationhttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/libraries/paginationhttp://docs.kohanaphp.com/libraries/profilerhttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/user_agenthttp://docs.kohanaphp.com/helpers/cookiehttp://docs.kohanaphp.com/libraries/database/configurationhttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/general/i18nhttp://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/libraries/paginationhttp://docs.kohanaphp.com/libraries/profilerhttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/user_agent8/6/2019 Kohana Doc
23/161
view.php
Allowed file types (deprecated?)
Kohana URLsURLs in Kohana are composed of segments. A typical segmented URL is
http://localhost/control/action/arg1/arg2
The segments correspond (in order ) to a controller, a controller method, and the method arguments.
Example
http://localhost/index.php?/articles/edit/1/my-first-article// or the same URL with url rewriting onhttp://localhost/articles/edit/1/my-first-article
When you segmentize this url it becomes
articles (the controller)
edit (the action)
1 (first argument)
my first article (second argument)
This will correspond to the controller articles found for example in
application/controllers/articles.php see Controllers for more information
The second segment maps to a method edit in the Articles_Controller class in
application/controllers/articles.php If no second segment is set it will call theindex() method. If a non existing method is set it will try to call _default() or trigger an 404.
The third and fourth segment refer to arguments given to the edit() method. E.g. edit($id,$title)
An example of what a controller would look like when this url is used.
Example
class Articles_Controller extends Controller {function __construct(){
parent::__construct();
}function index()
{}function edit($id,$title){
//get the article from the database and edit it echo $id;
$this->load->view('articles/edit');}
}
Segments
As said, Kohana urls contain segments.
http://localhost/control/action/arg1/arg2http://docs.kohanaphp.com/general/controllershttp://www.php.net/echohttp://localhost/control/action/arg1/arg2http://docs.kohanaphp.com/general/controllershttp://www.php.net/echo8/6/2019 Kohana Doc
24/161
Example
http://localhost/articles/edit/1/my-first-article
Contains the segments
articles
edit 1
my first article
AURI class and a URL helper provide methods to make working with a url easier. You can retrieve
segments, determine the current url segment, and various other operations.
URL rewriting
By default, Kohana urls contain index.php. This does not look very nice and also is not optimized
for search engines. See the difference between the following urls.
http://localhost/index.php?/articles/edit/1/my-first-article// or the same URL with url rewriting onhttp://localhost/articles/edit/1/my-first-article
The latter looks nicer and is SEO proof.
The following urls might be of interest when setting up such a system:
http://kohanaphp.com/tutorials/remove_index.html
http://forumarchive.kohanaphp.com/index.php/topic,246.0.html
They offer slightly different solutions but each should work equally good.
Suffix
Kohana allows you to set a suffix to your urls.
Example
http://localhost/index.php?/articles/edit/1/my-first-article.html
Setting this can be done in the application/config/config.php file under url_suffix
Allowed charactersSome characters are not allowed in urls. You can set the allowed characters in the
config/routes.php file. See for more information therouting page.
Query strings and GET support
Query strings and GET support are enabled in Kohana. You can simply append your urls with ?
var=value to pass it on. The keys and values are inspected and cleansed by the Input library when
global_xss is on.
http://docs.kohanaphp.com/libraries/urihttp://docs.kohanaphp.com/libraries/urihttp://docs.kohanaphp.com/helpers/urlhttp://kohanaphp.com/tutorials/remove_index.htmlhttp://forumarchive.kohanaphp.com/index.php/topic,246.0.htmlhttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/libraries/urihttp://docs.kohanaphp.com/helpers/urlhttp://kohanaphp.com/tutorials/remove_index.htmlhttp://forumarchive.kohanaphp.com/index.php/topic,246.0.htmlhttp://docs.kohanaphp.com/general/routing8/6/2019 Kohana Doc
25/161
RoutingTypically, a URI will map to a controller class and method on a one to one basis and provide
arguments where necessary. For example,
http://www.example.com/class/function/arg1/arg2
The first segment refers to the controller class, the second to a method in that class and any other
segments become that method's arguments.
There are cases, however, where you might want to change this behaviour. For example, you may
want to use URIs like this: www.example.com/article/22. Here, the second segment of theURI is an article number, which is an argument, not a controller method. The routing feature of
Kohana allows you to change how URIs are mapped to controllers and methods.
Kohana's routing configuration
In order to alter routing you have to have a copy ofroutes.php in yourapplication/config directory. If it is not already there copy the one from thesystem/config directory.
The default routes.php will have two entries:
$config['_allowed'] = '-a-z 0-9~%.,:_';
$config['_allowed'] determines which characters are allowed in a URI. When changingthis, take care not to allow characters in the URI that could compromise your application.
$config['_default'] = 'welcome';
$config['_default'] specifies the default route. It is used to indicate which controllershould be used when a URI contains no segments. For example, if your web application is at
www.example.com and you visit this address with a web browser, the welcome controllerwould be used even though it wasn't specified in the URI. The result would be the same as if the
browser had gone towww.example.com/welcome.
Specifying your own routes
In addition to the default route above, you can also specify your own routes. The basic format for a
routing rule is:$config['route'] = 'class/method';
where route is the URI you want to route, and class/method would replace it.
So, for example, if your Kohana web application were installed at www.example.comand youhad the following routing rule:
$config['test'] = 'foo/bar';
and you visitedwww.example.com/test in a web browser, you would see the page at
www.example.com/foo/bar.
http://www.example.com/article/22http://www.example.com/http://www.example.com/welcomehttp://www.example.com/welcomehttp://www.example.com/http://www.example.com/http://www.example.com/testhttp://www.example.com/testhttp://www.example.com/foo/barhttp://www.example.com/article/22http://www.example.com/http://www.example.com/welcomehttp://www.example.com/http://www.example.com/testhttp://www.example.com/foo/bar8/6/2019 Kohana Doc
26/161
8/6/2019 Kohana Doc
27/161
Loading libraries
Libraries can be loaded in general in two different ways. For example loading the session library:
$this->load->library('session');// the object can be approached with $this->session e.g.echo $this->session->id()
// this is the CodeIgniter compatible approach// another possiblity using PHP5's nifty auto_load function$session = new Session;echo $session->id();
Loading database
Apart from the aforementioned methods loading the database can also be done like this
$this->load->database();
Note: in models the database is loaded automatically.
Loading helpers
Note:
Loading a helper using $thisloadhelper() is deprecated, it won't work and will
trigger a debug error in the log.
Using a helper is fairly simple. Just call method as a static method. The class will be loaded
automaticallyecho url::base();
Loading views
Views are the final output of Kohana. They can be embedded into each other so as to help you in
making your site. There is more than one syntax to load a view. The actual rendering of a view is
not done when you load one. More on views can be found on theviews page Information on the
view class can be found on the view class page.
Example
$this->layout=new View('layouts/layout'); // will load the fileviews/layouts/layout.php//alternate syntax$this->layout=$this->load->view('layouts/layout');//will render the view$this->layout->render(TRUE);
Loading models
To load a model there is more than one method. These are the basic methods, more can be found on
theModels page.
http://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/core/viewshttp://docs.kohanaphp.com/general/modelshttp://docs.kohanaphp.com/general/modelshttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/core/viewshttp://docs.kohanaphp.com/general/models8/6/2019 Kohana Doc
28/161
8/6/2019 Kohana Doc
29/161
A simple controller
We start with a simple controller. It will show Hello World on the screen.
application/controllers/article.php
class Article_Controller extends Controller{
public function index(){
echo 'Hello World!';}
}
Now if you enter www.yoursite.com/article you should see
Hello World
That's it, your first controller. You can see all conventions are applied.
More advanced controller
In the example above the index() method is called by the www.yoursite.com/article url. If the second
segment of the url is empty, the index method is called. It would also be called by the following url:
www.yoursite.com/article/index
If the second segment of the url is not empty, it determines which method of the controller is called.
application/controllers/article.php
class Article_Controller extends Controller{
public function index(){ echo 'Hello World!';
}
public function overview(){
echo 'Article list goes here!';}
}
Now if you call the urlwww.yoursite.com/article/overview it will display
Article list goes here!
Controller with arguments
Say we want to display a specific article, for example the article with the title being your-article-title and the id of the article is 1.
The url would look like www.yoursite.com/article/view/your article title /1 The last two segments
of the url are passed on to the view() method.
application/controllers/article.php
class Article_Controller extends Controller{
public function index()
http://www.php.net/echohttp://www.yoursite.com/articlehttp://www.yoursite.com/articlehttp://www.yoursite.com/articlehttp://www.yoursite.com/article/indexhttp://www.php.net/echohttp://www.php.net/echohttp://www.yoursite.com/article/overviewhttp://www.yoursite.com/article/overviewhttp://www.yoursite.com/article/view/http://www.php.net/echohttp://www.yoursite.com/articlehttp://www.yoursite.com/articlehttp://www.yoursite.com/article/indexhttp://www.php.net/echohttp://www.php.net/echohttp://www.yoursite.com/article/overviewhttp://www.yoursite.com/article/view/8/6/2019 Kohana Doc
30/161
{ echo 'Hello World!';
}
public function overview(){
echo 'Article list goes here!';
}public function view($title,$id){
echo $id . ' - ' . $title;// you'd retrieve the article from the database here normally
}}
When you call www.yoursite.com/article/view/your article title /1 it will display
1 - your-article-title
Controllers and subdirectories
If you put a controller in a subdirectory of the /controllers/ directory, Kohana will include the
subdirectory in the mapping to the controller. E.g. a file in
application/controllers/admin/user.phpwill correspond to the urlhttp://localhost/admin/user
Routing controllers elsewhere
If for some reason the mapping from the URI to the controller and method is not right for you youcan use routing to map a URI to another controller. E.g. have localhost/about/me map to
http://localhost/articles/view/1
See Routingfor more information on this.
Special methods
index
index() is the method that will be called when there is no other method call. E.g. if your controlleris called Welcome_Controller, and the following url is called http://example.com/welcomethen the index method is called.
_remap
If you have this method in you controller, then all requests to the controller are sent to it, bypassing
the default URI to method mapping.
The method is passed two parameters which can be handled as in the example below:
class Article_Controller extends Controller{
public function _remap( $method, $data )
http://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.yoursite.com/article/view/http://localhost/admin/userhttp://localhost/admin/userhttp://localhost/admin/userhttp://localhost/articles/view/1http://docs.kohanaphp.com/general/routinghttp://docs.kohanaphp.com/general/routinghttp://example.com/welcomehttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.yoursite.com/article/view/http://localhost/admin/userhttp://localhost/admin/userhttp://localhost/articles/view/1http://docs.kohanaphp.com/general/routinghttp://example.com/welcome8/6/2019 Kohana Doc
31/161
{// method is the first part of the uri.// it'll be index if there is no segment following the controller name// or the segment if there is
// the $data param is an array of the remaining uri segments (if any)// otherwise it is an empty array
}}
Examples
www.domain.com/article
returns:
method = index
data = none
www.domain.com/article/read
returns:
method = read
data = none
www.domain.com/article/read/1
returns:
method = index
data = array( '1' );
You would not use _remap if your URI schema was this simple, but this shows how _remap works.
There is also a tutorial showing the use of _remap.
_default
_default() is the method called when a method of a controller is called that doesn't exist. E.g. http://
example.com/welcome/sthrandom90923 , the method sthrandom90923 doesn't exist so if it exists
_default() will be called. This is handy if you want to trigger a 404 for example.
Private methods
Sometimes you want some methods in your controller which should not be available on your
website. They are only used internally. This can be done by declaring methods private and/or
prepending them with _
application/controllers/home.php
class Article_Controller extends Controller{
public function index(){ echo 'Hello World!';
}
http://learn.kohanaphp.com/2008/03/26/using-_remap/http://example.com/welcome/sthrandom90923http://example.com/welcome/sthrandom90923http://www.php.net/echohttp://learn.kohanaphp.com/2008/03/26/using-_remap/http://example.com/welcome/sthrandom90923http://example.com/welcome/sthrandom90923http://www.php.net/echo8/6/2019 Kohana Doc
32/161
private function _article_form(){
echo 'Article form';}
}
When you call www.yoursite.com/article/_article_form you'll encounter a 404.
Class constructors
If you declare a constructor in your controller, for example to load some resources for the entire
controller, you have to call the parent constructor.
application/controllers/home.php
class Article_Controller extends Controller{
protected $db;
protected $session;
public function __construct(){
parent::__construct(); //this must be included
$this->db = new Database;$this->session = new Session;
}
public function index(){
$this->session->get('user_id');}
public function view($article_id){
$article_id = (int) $article_id;$article = $this->db->getwhere('articles', array('id' => $article_id));
}}
This example also shows how you can retrieve an article from the database using URL segments. If
you callwww.yoursite.com/article/view/5 , it will retrieve the article whose id is 5.
Special Controllers
Using a base controller for your application
Using a base controller for your application can be very helpful. You can execute code on every
page for example, useful for authenticating and authorizing users for example or doing session
magic.
ExampleMY_Controller.php
8/6/2019 Kohana Doc
33/161
public function __construct(){
parent::__construct();
// authentication goes here for example}
public function do_something(){// method available in all controllers
}}
The file should be named MY_Controller.php It should then be placed inapplication/libraries This class has all the methods of the original Controller plus yourown.
Note: The prefix MY_ can be configured in application/config/config.php bychanging the $config['extension_prefix']
LibrariesThe following Kohana libraries are loaded automatically by the framework and should always be
available to you:
Loader
URI
Input
Other libraries can be loaded automatically by Kohana when they are used. For example, to load and
use the Profiler library, you can just add the following line to your controller's constructor:
$this->profiler = new Profiler;
Alternatively, if you wish to load libraries manually, you can do the following:
$this->load->library('some_library');
Note: using the above manual method of loading libraries is deprecated since Kohana 2.1.2.
For more information, see the page on Loading.
Adding your own libraries
When creating your own libraries, these are the conventions that are suggested:
Library files should be put in application/libraries (or if you're creating a module,in modules/libraries)
Library files must be named the same as the library class (but without any _Core suffix). Library class names must be all capitalized (I.e., the first letter must be a upper case)
For a new library, the class name can have _Core appended to the end to enable you toextend it in the same way you can with Kohana's built in libraries.
For example, lets suppose that you wanted to create a new book library. You might create thefollowing file:
http://docs.kohanaphp.com/general/loadinghttp://docs.kohanaphp.com/general/loading8/6/2019 Kohana Doc
34/161
File: application/libraries/Book.php
Extending libraries
Kohana also allows you to extended it's built in libraries so that you can add your own functionality
to them, or change the way they work. You should never change the files in
system/libraries. Instead you can create a new library that extends a built in library.
You can also extend your own libraries, so long as you have added _Core to the end of theirclass names.
When extending a library, the conventions are the same as for when you are creating a new library,
with a couple of exceptions:
The filename must be prefixed with MY_. This prefix is configurable; see theconfiguration page.
The class name must be the same as the class name you are extending and must not have
_Core appended to it.
Lets say, for example, that you want to extend Kohana's controller class. You might do the
following:
File:application/libraries/MY_Controller.php
8/6/2019 Kohana Doc
35/161
application.
The deprecated preloadconfiguration option (which pre loads libraries and models) has beenreplaced by this method. The same behaviour can be achieved by extending the core Controller class
and loading any libraries and models from the constructor.
Replacing Kohana's built in librariesIt is also possible (although probably less often required) to replacing one of Kohana's built in
libraries entirely. The conventions are the same as when you are adding your own library, with one
exception:
Appending _Core to the class name is not optional you must do it!
If, for example, you want to replace the Profiler library, you might create the following file:
File:application/libraries/Profiler.php
3rd party libraries
If you should require 3rd party libraries (such as Simplepie, Zend Framework, or Pear libraries) youcan place these in the application/vendors directory. Loading them from Kohana is simple.You might do the following:
Kohana::find_file('vendors','some_class')
For more information, see the Kohana class page.
Note that some 3rd party libraries can be adjusted to be Kohana libraries without much effort,
sometimes renaming the file and the class name is all that is necessary. If so, you can use an
alternative method of loading. You might do the following:
$this->load->library('some_lib');
Zend Framework
Zend Framework's files may struggle to load it's dependencies which will be loaded incorrectly
without further configuration. If the zend folder is in applications/vendor/zend thefollowing code can be used.
// make sure you put this somewhere before loading a Zend Framework componentini_set('include_path',ini_get('include_path').PATH_SEPARATOR.APPPATH.'vendor/zend/library/');
To include a Zend Framework component, you might do the following:
// example
http://docs.kohanaphp.com/general/configurationhttp://docs.kohanaphp.com/libraries/profilerhttp://www.php.net/definedhttp://www.php.net/diehttp://docs.kohanaphp.com/core/kohanahttp://www.php.net/ini_sethttp://www.php.net/ini_gethttp://docs.kohanaphp.com/general/configurationhttp://docs.kohanaphp.com/libraries/profilerhttp://www.php.net/definedhttp://www.php.net/diehttp://docs.kohanaphp.com/core/kohanahttp://www.php.net/ini_sethttp://www.php.net/ini_get8/6/2019 Kohana Doc
36/161
require_once 'Zend/Service/Flickr.php';// or another examplerequire_once 'Zend/Acl.php';$acl = new Zend_Acl();
Note that it also can be placed in the SYSPATH folder but it then might be overwritten by a new
version of Kohana. Module folders will do as well. In this case use
ini_set('include_path',ini_get('include_path').PATH_SEPARATOR.SYSPATH.'vendor/zend/library/');
HelpersHelpers are simply handy functions that help you with development.
Helpers are similar to library methods, but there is a subtle difference. With a library, you have to
create an instance of the library's class to use its methods. Helpers are declared as static methods ofa class, so there is no need to instantiate the class. You can think of them as global functions.
As with libraries, the helper classes are automatically loaded by the framework when they are used,
so there is no need to load them yourself.
Here is an example call to a helper:
// show the location of this Kohana installationecho url::base();
As with most of Kohana, you can add your own helpers and replace or extend Kohana's built in
ones.
Adding your own helpers
When creating your own helpers, these are the conventions that are suggested:
Helper files should be put in application/helpers (or if you're creating a module, inmodules/helpers)
Helper files must be named the same as the helper class (but without any _Core suffix). Helper class names must be all lowercase.
For a new helper, the class name can have _Core appended to the end to enable you to
extend it in the same way you can with Kohana's built in helpers.For example, suppose that you wanted to create a helper to help with JavaScript, you might create
the following file:
File:application/helpers/javascript.php
8/6/2019 Kohana Doc
37/161
?>
and then to use your helper, you would do the following:
javascript::alert("Oh no!");
Extending helpersKohana also allows you to extended its built in helpers so that you can add your own functionality to
them. You should never change the files in system/helpers! Instead, you can create a newhelper that extends a built in helper.
You can also extend your own helpers, so long as you have added _Core to the end of their classnames.
When extending a helper, the conventions are the same as for when you are creating a new helper,
with a couple of exceptions:
The filename must be the same as the helper you're extending, except it must have MY_prefixed to it. This prefix is configurable; see the configuration page.
The class name must be the same as the class name you are extending and must not have
_Core appended to it.
For example, lets suppose that you want to extend Kohana'sHTML helper. You might do the
following:
File:application/helpers/MY_html.php
Extending the core classes is not only allowed in Kohana, but is expected.
Replacing Kohana's built in helpersIt is also possible (although probably less often required) to replacing one of Kohana's built in
helpers entirely. The conventions are the same as when you are adding your own helper, with one
exception:
Appending _Core to the class name is not optional you must do it!
If, for example, you want to replace the url helper, you might do something like:
File:application/helpers/url.php
8/6/2019 Kohana Doc
38/161
}?>
ViewsSee View class for more in depth information on using views in your code.
Overview
Views are files that contain the display information for your application. This is most commonly
HTML, CSS and JavaScript but can be anything you require such as XML or Json for AJAX output.
The purpose of views is to keep this information separate from your application logic for easy
reusability and cleaner code.
While this is true, views themselves can contain code used for displaying the data you pass intothem. For example, looping through an array of product information and display each one on a new
table row. Views are still PHP files so you can use any code you normally would. Views are
executed in the Controller namespace so you have access to all resources you have loaded into
$this
When this view is rendered it is executed just as any PHP script would and the output from it is
returned (or sent to the browser if you so wish).
Creating views
Views need to be placed in the views directory. The filename minus the extension becomes theview's name. Views can be arranged in sub directories if needed but the path must be specified
when loading them.
Examples
// Filename home.php$view = new View('home');// Filename list.php in sub-directory 'products'$view = new View('products/list');
Loading views
There are 3 ways to load a view. It is important to note that this simply creates an instance of the
View class, at this point the view file has not been read and no output is created. This only happens
when it is rendered.
New object
Create a new instance of the class.
$view = new View('welcome');
http://docs.kohanaphp.com/core/viewhttp://docs.kohanaphp.com/core/view8/6/2019 Kohana Doc
39/161
Factory
Use the factory() static method. This is essentially the same as creating a new object except it is
immediately returned so method chaining is possible.
$view = View::factory('welcome');
Loader
Since Kohana 2.1.2 loader is deprecated.
Use the built in loader. Using the factory method is preferred over this as it does the exact same
thing but factory is shorter and clearer. The loader method is mainly provided for easier migration
from CodeIgniter.
$view = $this->load->view('welcome');
Passing data into your viewsData is passed from the controller to the view by way of an an object.
Let's look at the Controller:
class Welcome_Controller extends Controller {
function index(){
// Load the view as an object$view = new View('yourview');
// Adding variables to the object that will be displayed in the view$view->title = "Welcome to Kohana !";$view->heading = "My Heading";$view->content = "My content here.";
// Render the view$view->render(TRUE);
}}
Now open your view file and add variables:
Note:
Use of arrays (CodeIgniter style) is still possible in Kohana, see more examples below
Note:
You cannot use $view data = $data;
http://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echo8/6/2019 Kohana Doc
40/161
Views within views
To load views within other views:
// Example of code inside your Controller$view = new View('template');
$view->header = new View('header');$view->content = new View('content');$view->footer = new View('footer');$view->header->title = 'Title of page'; // string for variable $title inview header.php$view->content->heading = 'Heading of your page'; // string for variable$heading in view content.php$view->footer->copyright = 'Copyright'; // string for variable $headingin view footer.php$view->render(TRUE);
View: template.php
View: header.php
View: content.php
View: footer.php
Output:
Title of page
Heading of your page
Copyright
Of course, using stylesheets and applying them to divs within your layout would give the exact
design you want. You may also need custom helpers to generate navigation, breadcrumbs anddynamic content (banners, customized ads) to add a professional touch.
Note: Please also consider using the Template_Controller, this can merge the header.php and
http://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://december.com/html/4/element/html.htmlhttp://december.com/html/4/element/head.htmlhttp://december.com/html/4/element/title.htmlhttp://december.com/html/4/element/body.htmlhttp://december.com/html/4/element/h1.htmlhttp://docs.kohanaphp.com/addons/templatehttp://docs.kohanaphp.com/addons/templatehttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://www.php.net/echohttp://december.com/html/4/element/html.htmlhttp://december.com/html/4/element/head.htmlhttp://december.com/html/4/element/title.htmlhttp://december.com/html/4/element/body.htmlhttp://december.com/html/4/element/h1.htmlhttp://docs.kohanaphp.com/addons/template8/6/2019 Kohana Doc
41/161
footer.php into one file.
Data scope
RenderingExecute the render method on the view instance.
Examples
Ex 1: Render on View instance
$view = new View('sample');$view->render(TRUE);
Ex 2: Render on View::factory
View::factory('sample')->render(TRUE);
Complete Example
Controller: products.php
$products = array( array(
'name' => 'Product1','quantity' => '3'
),
array('name' => 'Product2','quantity' => '7'
));$view = new View('products/list');$view->title = 'Products';$view->set('products', $products);$view->render(TRUE);
An array of product data is defined. The products list view is loaded and the variables title and
products are set. The view is rendered and outputted straight to the browser.View: products/list.php
8/6/2019 Kohana Doc
42/161
echo $product['quantity']; echo '';
}?>
The title variable is echo'd. The products array is iterated over and each product is echo'dwithin table row and column tags.
Output:
Products Products
Product13 Product27
Models
What are models?Models are classes designed to work with information given by or asked for by the controller. For
example, you have a guestbook, the controller will ask the model to retrieve the last ten entries, the
model returns those entries to the controller who passes them on to a view. The controller might
also send new entries to the model, update existing ones or even delete some.
Note that Kohana doesn't force you to use models. If you choose not to use them, you are free to do
so.
Naming modelsKohana uses specific rules for the naming of models. These are:
Models go into the application/models/ directory. Model filenames are lowercase, do not have _model appended to them and should be the
singular form of the name.
The model class name is capitalized, does have _Model appended to it and should be the
singular form of the name.
For models that use ORM, there are other, more specific, conventions.
Example
Suppose that you have a table in the database called users (which is a plural name). The model
http://www.php.net/echohttp://www.php.net/echohttp://december.com/html/4/element/html.htmlhttp://december.com/html/4/element/head.htmlhttp://december.com/html/4/element/title.htmlhttp://december.com/html/4/element/body.htmlhttp://december.com/html/4/element/h1.htmlhttp://december.com/html/4/element/table.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://docs.kohanaphp.com/libraries/ormhttp://www.php.net/echohttp://www.php.net/echohttp://december.com/html/4/element/html.htmlhttp://december.com/html/4/element/head.htmlhttp://december.com/html/4/element/title.htmlhttp://december.com/html/4/element/body.htmlhttp://december.com/html/4/element/h1.htmlhttp://december.com/html/4/element/table.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/tr.htmlhttp://december.com/html/4/element/td.htmlhttp://december.com/html/4/element/td.htmlhttp://docs.kohanaphp.com/libraries/orm8/6/2019 Kohana Doc
43/161
that represents the users table would reside in the file application/models/user.phpand the class would be called User_Model (which are both singular names).
The file would initially look something like this:
8/6/2019 Kohana Doc
44/161
public function __construct($id = NULL){
// load database library into $this->db (can be omitted if notrequired)
parent::__construct($id);}
/*** Get information about a user, given their user_id* @param integer the user_id* @return the result object*/
public function get_user($user_id){
$this->db->where('user_id', $user_id);return $this->db->get('users');
}
/**
* Add a new user. Assumes an auto incrementing user_id in the database.* @param array user data. E.g.,* array( 'name' => 'test', 'email' => 'test@example.com' )* @return void*/
public function insert_user($data){
$this->db->insert('users', $data);}
/*** Replace user details.* @param array user data. E.g.,
* array( 'name' => 'test', 'email' => 'test@example.com' )* @return void*/
public function update_user($user_id, $data){
$this->db->where('user_id', $user_id);$this->db->update('users', $data);
}}
Note: When utilizing data from a form always use $thisinputpost('var_name',
TRUE) to ensure data is sanitized before using. Learn more about the Input library.
Using a database in your model
If your model's constructor contains the line parent::__construct();, the default databasefunctionality will be loaded into $thisdb. You can use all of the database's functions with the$thisdb object.
Using a model in your controller
Using the example model above, you can integrate this model into your controller as follows:
1. Create an instance of the model in your controller to make it accessible. This can be done
http://docs.kohanaphp.com/libraries/inputhttp://docs.kohanaphp.com/libraries/input8/6/2019 Kohana Doc
45/161
directly in a controller method as $user = new User_Model. If you want the modelaccessible from all of your controller methods, create an instance of the model in your
controller constructor: $thisuser = new User_Model.2. If you used the constructor method above, you can now retrieve user information from your
database within any of your controller methods with: $user =$thisuserget_user(1). The $user variable now contains a database result set
object (for the user with id = 1) that can be passed to your View.3. If you passed the entire $user variable to your View, you can access specific user data
elements within your View in the form $username. See Database Library for moreinformation.
ORM
See for more information
ORM
ORM is a special kind of model. Based on its name it will derive for example the table it is a modelfor, it will also have some basic functions (find($id), find_all_by_lastname) commonly used in a
model as well as support for relationships between tables. Another aspect of ORM is that it turns a
record from a database into an object.
EventsSee Event for information on adding, running, removing and using custom events.
Kohana events consist of a name andcallback. Names usually include a prefix with the name 1), but
are not required to. All of the core events are prefixed as system.name.
System Events
The following events are defined in the Kohana core files. The pre defined actions for these events
are added in Kohana::setup.
system.ready
Called immediately after hooks are loaded. This is the earliest attachable event. Nothing is attached
to this event by default. Hooks are loaded before this point.
system.routing
Processes the URL and does routing. CallsRouter::find_uri and Router::setup by default.
system.execute
Controller locating and initialization. A controller object will be created, as an instance of Kohana.
CallsKohana::instanceby default.
system.post_routing
Kohana 2.2 Triggered after all routing is done so interventions in routing can be done here. If
http://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/libraries/database/resulthttp://docs.kohanaphp.com/libraries/ormhttp://docs.kohanaphp.com/core/eventhttp://php.net/manual/en/language.pseudo-types.php#language.types.callbackhttp://php.net/manual/en/language.pseudo-types.php#language.types.callbackhttp://docs.kohanaphp.com/general/events#fn__1http://docs.kohanaphp.com/general/events#fn__1http://docs.kohanaphp.com/core/kohana#setuphttp://docs.kohanaphp.com/libraries/router#setuphttp://docs.kohanaphp.com/libraries/router#setuphttp://docs.kohanaphp.com/libraries/router#setuphttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/general/viewshttp://docs.kohanaphp.com/libraries/database/resulthttp://docs.kohanaphp.com/libraries/ormhttp://docs.kohanaphp.com/core/eventhttp://php.net/manual/en/language.pseudo-types.php#language.types.callbackhttp://docs.kohanaphp.com/general/events#fn__1http://docs.kohanaphp.com/core/kohana#setuphttp://docs.kohanaphp.com/libraries/router#setuphttp://docs.kohanaphp.com/libraries/router#setuphttp://docs.kohanaphp.com/core/kohana#instance8/6/2019 Kohana Doc
46/161
Router::$controller is empty after this event a 404 is triggered.
system.404
Called when a page cannot be found. Calls Kohana::show_404 by default.
system.pre_controller
Called within system.execute, after the controller file is loaded, but before an object is created.
system.post_controller_constructor
Called within system.execute, after the controller constructor has been called. Kohana::instance will
return the controller at this point, and views can be loaded. Controller methods have not been called
yet.
system.post_controller
Called within system.execute, after the controller object is created. Kohana::instance will return the
controller at this point, and views can be loaded.
system.send_headers
Called just before the global output buffer is closed, before any content is displayed. Writing
cookies is not possible after this point, andSession data will not be saved.
system.display
Displays the output that Kohana has generated. Views can be loaded, but headers have already beensent. The rendered output can be manipulated asEvent::$data.
system.shutdown
Last event to run, just before PHP starts to shut down. Runs the Kohana::shutdown method by
default.
Hooks
Hooks are included early in Kohana and can be used to execute code before e.g. controllers areloaded so you can check for for example authentication early in Kohana. Events and hooks go hand
in hand since in hooks you can attach code to events. See for more information theHooks page.
1) An example of a prefix is prefix.name
HooksHooks are basically files included at the start of Kohana, to be more specific they are loaded in the
Kohana::setup() method. At this time these files are loaded, so their methods can be used
index.php core/Bootstrap.php
core/Benchmark.php
http://docs.kohanaphp.com/core/kohana#show_404http://docs.kohanaphp.com/general/events#system.executehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/general/events#system.executehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/general/events#datahttp://docs.kohanaphp.com/general/events#datahttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/general/events#fnt__1http://docs.kohanaphp.com/core/kohana#show_404http://docs.kohanaphp.com/general/events#system.executehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/general/events#system.executehttp://docs.kohanaphp.com/core/kohana#instancehttp://docs.kohanaphp.com/libraries/sessionhttp://docs.kohanaphp.com/general/events#datahttp://docs.kohanaphp.com/general/hookshttp://docs.kohanaphp.com/general/events#fnt__18/6/2019 Kohana Doc
47/161
core/utf8.php
core/Config.php
core/Log.php
core/Event.php
core/Kohana.php
No event has been started yet, the first to be started is system.readyHook files should be put in application/hooks or similarly in a module folder.
Configuring hooks
To configure hooks edit 'hooks.php in your application/config directory. If the file is not therecopy the one from system/config.
It will look something like this:
File: hooks.php
$config['enable'] = FALSE;
Set $config['enable'] to TRUE and all files in the hooks directory(application/hooks) will be included and the code will be executed.
Set $config['enable'] to an array with filenames and those and only those files will beincluded.
Example hooks.php
//To include all files in application/hooks$config['enable'] = TRUE;
//or to load page_cache.php$config['enable'] = array('page_cache');
Hooks and events
The power of hooks mainly comes from the Eventsclass. Hooks are loaded before any of the events
are started so you can attach a hook to an event. For example you load the following file as a hook
Example hooks/power.php
class Power {public function Kohana(){Event::$data=Event::$data.'';
}}Event::add('system.display', array('Power', 'Kohana'));
This will add a small notice to the bottom of each page (). It utilizes the
Event::$data to manipulate the final output.
ConstantsWhen using hooks you might need to get under the hood of Kohana. When the hooks are loaded
http://www.php.net/arrayhttp://docs.kohanaphp.com/core/eventhttp://docs.kohanaphp.com/core/eventhttp://www.php.net/arrayhttp://www.php.net/arrayhttp://docs.kohanaphp.com/core/eventhttp://www.php.net/array8/6/2019 Kohana Doc
48/161
these constants are set in index.php
EXT contains the default file extension used for files in Kohana. Defaults to '.php'
KOHANA basename
DOCROOT dirname
APPPATH path to the application directory
SYSPATH path to the system directory MODPATH path to the modules directory
Error HandlingSee for more information
Log class explanation of the log class.
Config.display_errors
In the index.php file there is a setting display_errors. This determines whether errors should be
outputted to the screen or not. During development you'd want to set this to TRUE, but in
production set this to FALSE so as to prevent users from seeing errors. This won't affect logging of
errors.
Exceptions
Exceptions in Kohana are handled by the Kohana Exception classes. There are three types of
exceptions:Kohana_Exception,Kohana_User_Exception and Kohana_404_Exception.
Kohana_Exception
Kohana_Exception extends Exception. To throw a Kohana_Exception an i18nlanguage file must exist.
Syntax
/*** @param string i18n language key for the message* @param array addition line parameters*/
throw new Kohana_Exception(string $i18_lang_key [, string $message]);
Example
//...if($x == 0)
throw new Kohana_Exception('math.division_by_zero');// Throw a $lang['division_by_zero'] exception in ./i18n/en_US/math.php// "Cannot divide by zero."
else if($x < 0)throw new Kohana_Exception('general.math.negative_number', $x);
// Throw a $lang['math']['negative_number'] exception in./i18n/en_US/general.php and pass the message $x
// "The number passed was negative: -5"//...
http://docs.kohanaphp.com/core/loghttp://docs.kohanaphp.com/general/errorhandling#kohana_exceptionhttp://docs.kohanaphp.com/general/errorhandling#kohana_exceptionhttp://docs.kohanaphp.com/general/errorhandling#kohana_user_exceptionhttp://docs.kohanaphp.com/general/errorhandling#kohana_user_exceptiRecommended