^Status|Draft|
^Todo|Expand examples, Proof read|



====== Helpers ======

Helpers 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 of a 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:
<code php>
// show the location of this Kohana installation
echo url::base();
</code>

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, in ''modules/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''
<code php>
<?php defined('SYSPATH') or die('No direct script access.');

class javascript_Core {

	public static function alert($message)
	{
		return "alert('$message');\n";
	}
}

?>
</code>

and then to use your helper, you would do the following:

<code php>
javascript::alert("Oh no!");
</code>


===== Extending helpers =====

Kohana also allows you to extend 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 new helper 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 class names.

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's [[helpers:html|HTML helper]]. You might do the following:

**File:** ''application/helpers/MY_html.php''
<code php>
<?php defined('SYSPATH') or die('No direct script access.');

class html extends html_Core {

	public static function your_custom_method()
	{
	}

}
?>
</code>

Extending the core classes is not only allowed in Kohana, but is expected.


===== Replacing Kohana's built-in helpers =====

It 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 [[helpers:url|url helper]], you might do something like:

**File:** ''application/helpers/url.php''
<code php>
<?php defined('SYSPATH') or die('No direct script access.');

class url_Core {
    
	// define your own url helper here

}

?>
</code>