# Bootstrap

The bootstrap is located at `application/bootstrap.php`.  It is responsible for setting up the Kohana environment and executing the main response. It is included by `index.php` (see [Request flow](flow))

[!!] The bootstrap is responsible for the flow of your application.  In previous versions of Kohana the bootstrap was in `system` and was somewhat of an unseen, uneditible force.  In Kohana 3 the bootstrap takes on a much more integral and versatile role.  Do not be afraid to edit and change your bootstrap however you see fit.

## Environment setup

First the bootstrap sets the timezone and the locale, and adds Kohana's autoloader so the [cascading filesystem](files) works.  You could add any other settings that all your application needed here.

~~~
// Sample excerpt from bootstrap.php with comments trimmed down

// Set the default time zone.
date_default_timezone_set('America/Chicago');
 
// Set the default locale.
setlocale(LC_ALL, 'en_US.utf-8');
 
// Enable the Kohana auto-loader.
spl_autoload_register(array('Kohana', 'auto_load'));
 
// Enable the Kohana auto-loader for unserialization.
ini_set('unserialize_callback_func', 'spl_autoload_call');
~~~

## Initilization and Configuration

Kohana is then initialized by calling [Kohana::init], and the log and [config](files/config) reader/writers are enabled. 

~~~
// Sample excerpt from bootstrap.php with comments trimmed down

Kohana::init(array('
    base_url' => '/kohana/',
	index_file => false,
));

// Attach the file writer to logging. Multiple writers are supported.
Kohana::$log->attach(new Kohana_Log_File(APPPATH.'logs'));

// Attach a file reader to config. Multiple readers are supported.
Kohana::$config->attach(new Kohana_Config_File);
~~~

You can add conditional statements to make the bootstrap have different values based on certain settings.  For example, detect whether we are live by checking `$_SERVER['HTTP_HOST']` and set caching, profiling, etc. accordingly.  This is just an example, there are many different ways to accomplish the same thing.

~~~
// Excerpt from http://github.com/isaiahdw/kohanaphp.com/blob/f2afe8e28b/application/bootstrap.php
... [trimmed]
 
/**
 * Set the environment status by the domain.
 */
if (strpos($_SERVER['HTTP_HOST'], 'kohanaphp.com') !== FALSE)
{
	// We are live!
	Kohana::$environment = Kohana::PRODUCTION;
 
	// Turn off notices and strict errors
	error_reporting(E_ALL ^ E_NOTICE ^ E_STRICT);
}
 
/**
 * Initialize Kohana, setting the default options.
 ... [trimmed]
 */
Kohana::init(array(
	'base_url'   => Kohana::$environment === Kohana::PRODUCTION ? '/' : '/kohanaphp.com/',
	'caching'    => Kohana::$environment === Kohana::PRODUCTION,
	'profile'    => Kohana::$environment !== Kohana::PRODUCTION,
	'index_file' => FALSE,
));

... [trimmed]

try
{
	$request = Request::instance()->execute();
}
catch (Exception $e)
{
	// If we are in development and the error wasn't a 404, show the stack trace.
	if ( Kohana::$environment == "development" AND $e->getCode() != 404 )
	{
		throw $e;
	}
...[trimmed]
~~~

[!!] Note: The default bootstrap will set `Kohana::$environment = $_ENV['KOHANA_ENV']` if set. Docs on how to supply this variable are available in your web server's documentation (e.g. [Apache](http://httpd.apache.org/docs/1.3/mod/mod_env.html#setenv), [Lighttpd](http://redmine.lighttpd.net/wiki/1/Docs:ModSetEnv#Options)). This is considered better practice than many alternative methods to set `Kohana::$enviroment`, as you can change the setting per server, without having to rely on config options or hostnames.

## Modules

**Read the [Modules](modules) page for a more detailed description.**

[Modules](modules) are then loaded using [Kohana::modules()].  Including modules is optional.  

Each key in the array should be the name of the module, and the value is the path to the module, either relative or absolute.
~~~
// Example excerpt from bootstrap.php

Kohana::modules(array(
	'database'   => MODPATH.'database',
	'orm'        => MODPATH.'orm',
	'userguide'  => MODPATH.'userguide',
));
~~~

## Routes

**Read the [Routing](routing) page for a more detailed description and more examples.**

[Routes](routing) are then defined via [Route::set()].  

~~~
// The default route that comes with Kohana 3
Route::set('default', '(<controller>(/<action>(/<id>)))')
	->defaults(array(
		'controller' => 'welcome',
		'action'     => 'index',
	));
~~~

## Execution

Once our environment is initialized and routes defined, it's time to execute our application.  This area of the bootstrap is very flexible.  Do not be afraid to change this around to whatever suits your needs. 

### Basic Example
The most simple way to do this, and what comes default with Kohana 3 is simply:
~~~
// Execute the main request
echo Request::instance()
	->execute()
	->send_headers()
	->response;
~~~

### Catching Exceptions

**See [Error Handling](errors) for a more detailed description and more examples.**

The previous example provides no error catching, which means if an error occurs a stack trace would be shown which could show sensitive info, as well as be unfriendly for the user.  One way to solve this is to add a `try catch` block.  If we get an exception, we will show the view located at `views/errors/404.php`.  **Note: Because we catch the exception, Kohana will not log the error!  It is your responsibility to log the error.**

~~~
try
{
	// Execute the main request
	$request = Request::instance()->execute();
}
catch (Exception $e)
{
	// Be sure to log the error
	Kohana::$log->add(Kohana::ERROR, Kohana::exception_text($e));
	
	// If there was an error, send a 404 response and display an error
	$request->status   = 404;
	$request->response = View::factory('errors/404');
}

// Send the headers and echo the response
$request->send_headers();
echo $request->response;
~~~