^Status|Draft|
^Todo|Very rough, needs expanding and rewriting to read better. Include paths especially|

====== 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 table, a row in a specific table, or an HTML form.
    * Views are used as data-to-HTML rendering layers.
    * Controllers are used as the "entry point". They also direct and control the process flow of the application, and handle how a URI is converted into an application function.
    * Libraries are used as tools that operate on some form of pre-existing data, either in the form of an array (e.g., [[libraries:Session]], [[libraries:Validation]], [[libraries:Input]]) or some other data structure, such as [[libraries:ORM]] (database table) or [[libraries: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
   |    +- 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 [[:general:views|view]] file called ''layout.php'' in the ''application/views'' **and** ''system/views'' directories, the one in ''application'' will be returned when ''layout.php'' is searched 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.


[[http://upload.wikimedia.org/wikipedia/en/1/1c/Kohana-modules.png|{{http://upload.wikimedia.org/wikipedia/en/thumb/1/1c/Kohana-modules.png/512px-Kohana-modules.png}}]]



===== 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 [[:general:modules|Modules]] on how to set these up.

The ''application'' and ''system'' directories can be thought of as hardcoded modules. They are treated no differently from regular modules apart from the exceptions listed below.

===== Exceptions =====

There are 2 main exceptions in the filesystem:

''config.php'' **MUST** reside in the ''application/config'' directory. It will not be read if it exists within a module or the ''system'' directory. The reason for this is that it contains the ''modules'' setting which must be read before all others so the framework knows where the rest of the config files are along the include path.

The core files as part of ''system/core'' are also not cascading. They are hardcoded into the Kohana 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 in files lower down.

See [[:general:configuration|Configuration]] and [[:general:i18n|Internationalization]] for more information on this.

===== Built in directories =====

==== cache ====

By default, the [[:libraries:cache|Cache 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 the [[:core:config|Config class]] must be stored here.

==== controllers ====

All [[:general:controllers|controllers]] to be directed to by the [[:general:routing|router]] must go in here.

==== helpers ====

See [[:general:helpers|Helpers]].

==== hooks ====

See [[:general:hooks|Hooks]].

==== i18n ====

Language files read by [[:core:kohana#kohanalang|Kohana::lang()]] are stored here. They are split up into sub-directories using the country code and locale as the name. See [[:general:i18n|Internationalization]].

==== libraries ====

See [[:general:libraries|Libraries]].

==== logs ====

By default, log files generated by the [[:core:log|Log class]] are stored in the ''application/logs'' directory.

==== models ====

See [[:general:models|Models]].


==== vendor ====

3rd party libraries and scripts that are not integrated into Kohana should be stored here. See [[general:libraries|Libraries]] for more information.

==== views ====

See [[:general:views|Views]].