Kohana v3.3.0

system/guide/kohana/files/classes.md

@@ -0,0 +1,41 @@
+# Classes
+
+TODO: Brief intro to classes.
+
+[Models](mvc/models) and [Controllers](mvc/controllers) are classes as well, but are treated slightly differently by Kohana.  Read their respective pages to learn more.
+
+## Helper or Library?
+
+Kohana 3 does not differentiate between "helper" classes and "library" classes like in previous versions.  They are all placed in the `classes/` folder and follow the same conventions.  The distinction is that in general, a "helper" class is used statically,  (for examples see the [helpers included in Kohana](helpers)), and library classes are typically instantiated and used as objects (like the [Database query builders](../database/query/builder)).  The distinction is not black and white, and is irrelevant anyways, since they are treated the same by Kohana.
+
+## Creating a class
+
+To create a new class, simply place a file in the `classes/` directory at any point in the [Cascading Filesystem](files), that follows the [Class naming conventions](conventions#class-names-and-file-location).  For example, lets create a `Foobar` class.
+
+	// classes/Foobar.php
+	
+	class Foobar {
+		static function magic() {
+			// Does something
+		}
+	}
+	
+We can now call `Foobar::magic()` any where and Kohana will [autoload](autoloading) the file for us.
+
+We can also put classes in subdirectories.
+
+	// classes/Professor/Baxter.php
+	
+	class Professor_Baxter {
+		static function teach() {
+			// Does something
+		}
+	}
+	
+We could now call `Professor_Baxter::teach()` any where we want.
+
+For examples of how to create and use classes, simply look at the 'classes' folder in `system` or any module.
+
+## Namespacing your classes
+
+TODO: Discuss namespacing to provide transparent extension functionality in your own classes/modules.

system/guide/kohana/files/config.md

@@ -0,0 +1,84 @@
+# Config Files
+
+Configuration files are used to store any kind of configuration needed for a module, class, or anything else you want.  They are plain PHP files, stored in the `config/` directory, which return an associative array:
+
+    <?php defined('SYSPATH') OR die('No direct script access.');
+
+    return array(
+        'setting' => 'value',
+        'options' => array(
+            'foo' => 'bar',
+        ),
+    );
+
+If the above configuration file was called `myconf.php`, you could access it using:
+
+    $config = Kohana::$config->load('myconf');
+    $options = $config->get('options')
+
+## Merge
+
+Configuration files are slightly different from most other files within the [cascading filesystem](files) in that they are **merged** rather than overloaded. This means that all configuration files with the same file path are combined to produce the final configuration. The end result is that you can overload *individual* settings rather than duplicating an entire file.
+
+For example, if we wanted to change or add to an entry in the inflector configuration file, we would not need to duplicate all the other entries from the default configuration file.
+
+    // config/inflector.php
+
+    <?php defined('SYSPATH') OR die('No direct script access.');
+
+    return array(
+        'irregular' => array(
+            'die' => 'dice', // does not exist in default config file
+            'mouse' => 'mouses', // overrides 'mouse' => 'mice' in the default config file
+    );
+
+
+## Creating your own config files
+
+Let's say we want a config file to store and easily change things like the title of a website, or the google analytics code.  We would create a config file, let's call it `site.php`:
+
+    // config/site.php
+
+    <?php defined('SYSPATH') OR die('No direct script access.');
+
+    return array(
+        'title' => 'Our Shiny Website',
+        'analytics' => FALSE, // analytics code goes here, set to FALSE to disable
+    );
+
+We could now call `Kohana::$config->load('site.title')` to get the site name, and `Kohana::$config->load('site.analytics')` to get the analytics code.
+
+Let's say we want an archive of versions of some software.  We could use config files to store each version, and include links to download, documentation, and issue tracking.
+
+	// config/versions.php
+
+	<?php defined('SYSPATH') OR die('No direct script access.');
+	
+    return array(
+		'1.0.0' => array(
+			'codename' => 'Frog',
+			'download' => 'files/ourapp-1.0.0.tar.gz',
+			'documentation' => 'docs/1.0.0',
+			'released' => '06/05/2009',
+			'issues' => 'link/to/bug/tracker',
+		),
+		'1.1.0' => array(
+			'codename' => 'Lizard',
+			'download' => 'files/ourapp-1.1.0.tar.gz',
+			'documentation' => 'docs/1.1.0',
+			'released' => '10/15/2009',
+			'issues' => 'link/to/bug/tracker',
+		),
+		/// ... etc ...
+	);
+
+You could then do the following:
+
+	// In your controller
+	$view->versions = Kohana::$config->load('versions');
+	
+	// In your view:
+	foreach ($versions as $version)
+	{
+		// echo some html to display each version
+	}

system/guide/kohana/files/i18n.md

@@ -0,0 +1,67 @@
+# I18n
+
+Kohana has a fairly simple and easy to use i18n system. It is slightly modeled after gettext, but is not as featureful. If you need the features of gettext, please use that :)
+
+## __()
+
+Kohana has a __() function to do your translations for you. This function is only meant for small sections of text, not entire paragraphs or pages of translated text.
+
+To echo a translated string:
+
+	<?php echo __('Hello, world!');?>
+
+This will echo 'Home' unless you've changed the defined language, which is explained below.
+
+## Changing the displayed language
+
+Use the I18n::lang() method to change the displayed language:
+
+	I18n::lang('fr');
+
+This will change the language to 'es-es'.
+
+## Defining language files
+
+To define the language file for the above language change, create a `i18n/fr.php` that contains:
+
+	<?php
+	
+	return array
+	(
+		'Hello, world!' => 'Bonjour, monde!',
+	);
+
+Now when you do `__('Hello, world!')`, you will get `Bonjour, monde!`
+
+## I18n variables
+
+You can define variables in your __() calls like so:
+
+	echo __('Hello, :user', array(':user' => $username));
+
+Your i18n key in your translation file will need to be defined as:
+
+	<?php
+	
+	return array
+	(
+		'Hello, :user' => 'Bonjour, :user',
+	);
+
+## Defining your own __() function
+
+You can define your own __() function by simply defining your own i18n class:
+
+	<?php
+	
+	class I18n extends Kohana_I18n
+	{
+		// Intentionally empty
+	}
+	
+	function __($string, array $values = NULL, $lang = 'en-us')
+	{
+		// Your functionality here
+	}
+
+This will cause the built-in __() function to be ignored.

system/guide/kohana/files/messages.md

@@ -0,0 +1,36 @@
+# Messages
+
+Kohana has a robust key based lookup system so you can define system messages.
+
+## Getting a message
+
+Use the Kohana::message() method to get a message key:
+
+	Kohana::message('forms', 'foobar');
+
+This will look in the `messages/forms.php` file for the `foobar` key:
+
+	<?php
+	
+	return array(
+		'foobar' => 'Hello, world!',
+	);
+
+You can also look in subfolders and sub-keys:
+
+	Kohana::message('forms/contact', 'foobar.bar');
+
+This will look in the `messages/forms/contact.php` for the `[foobar][bar]` key:
+
+	<?php
+	
+	return array(
+		'foobar' => array(
+			'bar' => 'Hello, world!',
+		),
+	);
+
+## Notes
+
+ * Don't use __() in your messages files, as these files can be cached and will not work properly.
+ * Messages are merged by the cascading file system, not overwritten like classes and views.