Updated to KH 3.3 and improved

includes/kohana/modules/orm/guide/orm/examples/simple.md

@@ -67,7 +67,7 @@ This is a simple example of a single ORM model, that has no relationships, but u
 			 */
 			
 			// Create an instance of a model
-			$members = ORM::factory('member');
+			$members = ORM::factory('Member');
 			
 			// Get all members with the first name "Peter" find_all()
 			// means we get all records matching the query.
@@ -81,7 +81,7 @@ This is a simple example of a single ORM model, that has no relationships, but u
 			 */
 			
 			// Create an instance of a model
-			$member = ORM::factory('member');
+			$member = ORM::factory('Member');
 			
 			// Get a member with the user name "bongo" find() means
 			// we only want the first record matching the query.
@@ -92,7 +92,7 @@ This is a simple example of a single ORM model, that has no relationships, but u
 			 */
 			
 			// Create an instance of a model
-			$member = ORM::factory('member');
+			$member = ORM::factory('Member');
 			
 			// Do an INSERT query
 			$member->username = 'bongo';
@@ -106,7 +106,7 @@ This is a simple example of a single ORM model, that has no relationships, but u
 			
 			// Create an instance of a model where the
 			// table field "id" is "1"
-			$member = ORM::factory('member', 1);
+			$member = ORM::factory('Member', 1);
 			
 			// Do an UPDATE query
 			$member->username = 'bongo';

includes/kohana/modules/orm/guide/orm/examples/validation.md

@@ -44,7 +44,7 @@ This example will create user accounts and demonstrate how to handle model and c
 		public function username_available($username)
 		{
 			// There are simpler ways to do this, but I will use ORM for the sake of the example
-			return ORM::factory('member', array('username' => $username))->loaded();
+			return ORM::factory('Member', array('username' => $username))->loaded();
 		}
 
 		public function hash_password($password)
@@ -85,7 +85,7 @@ Please forgive my slightly ugly form. I am trying not to use any modules or unre
 
 		if ($_POST)
 		{
-			$member = ORM::factory('member')
+			$member = ORM::factory('Member')
 				// The ORM::values() method is a shortcut to assign many values at once
 				->values($_POST, array('username', 'password'));
 

includes/kohana/modules/orm/guide/orm/filters.md

@@ -1,21 +1,40 @@
 # Filters
 
-Filters in ORM work much like they used to when they were part of the Validate class in 3.0.x however they have been modified to match the flexible syntax of [Validation] rules in 3.1.x. Filters run as soon as the field is set in your model and should be used to format the data before it is inserted into the Database.
+Filters in ORM work much like they used to when they were part of the Validate class in 3.0.x. However, they have been modified to match the flexible syntax of [Validation] rules in 3.1.x.
 
-Define your filters the same way you define rules, as an array returned by the `ORM::filters()` method like the following:
+Filters run as soon as the field is set in your model and should be used to format the data before it is inserted into the Database. Filters are defined the same way you define [rules](validation), as an array returned by the `ORM::filters()` method, like the following:
 
 	public function filters()
 	{
 		return array(
+			// Field Filters
+			// $field_name => array(mixed $callback[, array $params = array(':value')]),
 			'username' => array(
+				// PHP Function Callback, default implicit param of ':value'
 				array('trim'),
 			),
 			'password' => array(
-				array(array($this, 'hash_password')),
+				// Callback method with object context and params
+				array(array($this, 'hash_password'), array(':value', Model_User::salt())),
 			),
 			'created_on' => array(
+				// Callback static method with params
 				array('Format::date', array(':value', 'Y-m-d H:i:s')),
 			),
+			'other_field' => array(
+				// Callback static method with implicit param of ':value'
+				array('MyClass::static_method'),
+				// Callback method with object context with implicit param of ':value'
+				array(array($this, 'change_other_field')),
+				// PHP function callback with explicit params
+				array('str_replace', array('luango', 'thomas', ':value'),
+				// Function as the callback (PHP 5.3+)
+				array(function($value) {
+					// Do something to $value and return it.
+					return some_function($value);
+				}),
+			),
+
 		);
 	}
 

includes/kohana/modules/orm/guide/orm/menu.md

@@ -7,3 +7,4 @@
 - [Examples](examples)
     - [Simple](examples/simple)
     - [Validation](examples/validation)
+- [Upgrading](upgrading)

includes/kohana/modules/orm/guide/orm/relationships.md

@@ -37,7 +37,7 @@ If you wanted access a post's author by using code like `$post->author` then you
 
 	protected $_belongs_to = array(
 		'author' => array(
-			'model'       => 'user',
+			'model'       => 'User',
 		),
 	);
 
@@ -68,7 +68,7 @@ Let's assume now you want to access the posts using the name `stories` instead,
 
 	protected $_has_many = array(
 		'stories' => array(
-			'model'       => 'post',
+			'model'       => 'Post',
 			'foreign_key' => 'author_id',
 		),
 	);
@@ -79,7 +79,7 @@ A `has_one` relationship is almost identical to a `has_many` relationship.  In a
 
 	protected $_has_one = array(
 		'story' => array(
-			'model'       => 'post',
+			'model'       => 'Post',
 			'foreign_key' => 'author_id',
 		),
 	);
@@ -92,7 +92,7 @@ To define the `has_many` "through" relationship, the same syntax for standard ha
 
 	protected $_has_many = array(
 		'categories' => array(
-			'model'   => 'category',
+			'model'   => 'Category',
 			'through' => 'categories_posts',
 		),
 	);
@@ -101,7 +101,7 @@ In the Category model:
 
 	protected $_has_many = array(
 		'posts' => array(
-			'model'   => 'post',
+			'model'   => 'Post',
 			'through' => 'categories_posts',
 		),
 	);

includes/kohana/modules/orm/guide/orm/upgrading.md

@@ -0,0 +1,16 @@
+# Upgrading
+
+## Table aliases
+
+ORM [will now alias the main table](http://dev.kohanaframework.org/issues/4066) in a query to the model's singular object name.
+i.e. Prior to 3.2 ORM set the from table like so:
+
+	$this->_db_builder->from($this->_table_name);
+
+As of 3.2 it is now aliased like so:
+
+	$this->_db_builder->from(array($this->_table_name, $this->_object_name));
+
+If you have a model `Model_Order` then when building a query use the alias like so:
+
+	$model->where('order.id', '=', $id);

includes/kohana/modules/orm/guide/orm/using.md

@@ -4,7 +4,7 @@
 
 To create a new `Model_User` instance, you can do one of two things:
 
-	$user = ORM::factory('user');
+	$user = ORM::factory('User');
 	// Or
 	$user = new Model_User();
 
@@ -12,7 +12,7 @@ To create a new `Model_User` instance, you can do one of two things:
 
 To insert a new record into the database, create a new instance of the model:
 
-	$user = ORM::factory('user');
+	$user = ORM::factory('User');
 
 Then, assign values for each of the properties;
 
@@ -33,11 +33,11 @@ Insert the new record into the database by running [ORM::save]:
 To find an object you can call the [ORM::find] method or pass the id into the ORM constructor:
 
 	// Find user with ID 20
-	$user = ORM::factory('user')
+	$user = ORM::factory('User')
 		->where('id', '=', 20)
 		->find();
 	// Or
-	$user = ORM::factory('user', 20);
+	$user = ORM::factory('User', 20);
 
 ## Check that ORM loaded a record
 
@@ -70,6 +70,25 @@ And if you want to save the changes you just made back to the database, just run
 
 To delete an object, you can call the [ORM::delete] method on a loaded ORM model.
 
-	$user = ORM::factory('user', 20);
+	$user = ORM::factory('User', 20);
 	$user->delete();
 
+	
+## Mass assignment
+	
+
+To set multiple values at once, use [ORM::values]
+	
+	try
+	{
+		$user = ORM::factory('user')
+			->values($this->request->post(), array('username','password'))
+			->create();
+	}
+	catch (ORM_Validation_Exception $e)
+	{
+		// Handle validation errors ...
+	}
+	
+[!!] Although the second argument is optional, it is *highly recommended* to specify the list of columns you expect to change. Not doing so will leave your code _vulnerable_ in case the attacker adds fields you didn't expect.
+

includes/kohana/modules/orm/guide/orm/validation.md

@@ -41,7 +41,7 @@ All models automatically validate their own data when `ORM::save()`, `ORM::updat
 	{
 		try
 		{
-			$user = ORM::factory('user');
+			$user = ORM::factory('User');
 			$user->username = 'invalid username';
 			$user->save();
 		}
@@ -61,7 +61,7 @@ In the below example, the error messages will be defined in `application/message
 	{
 		try
 		{
-			$user = ORM::factory('user');
+			$user = ORM::factory('User');
 			$user->username = 'invalid username';
 			$user->save();
 		}
@@ -79,7 +79,7 @@ Certain forms contain information that should not be validated by the model, but
 	{
 		try
 		{
-			$user = ORM::factory('user');
+			$user = ORM::factory('User');
 			$user->username = $_POST['username'];
 			$user->password = $_POST['password'];
 
@@ -108,4 +108,4 @@ Because the validation object was passed as a parameter to the model, any errors
 
 This ensures that errors from multiple validation objects and models will never overwrite each other.
 
-[!!] The power of the [ORM_Validation_Exception] can be leveraged in many different ways to merge errors from related models. Take a look at the list of [Examples](examples) for some great use cases.
+[!!] The power of the [ORM_Validation_Exception] can be leveraged in many different ways to merge errors from related models. Take a look at the list of [Examples](examples) for some great use cases.