Including documentation about Ardent::$relationsData

Author: igorsantos07

README.md

@@ -22,7 +22,7 @@ Update your packages with `composer update` or install with `composer install`.
 
 You can also add the package using `composer require laravelbook/ardent` and later specifying the version you want (for now, `dev-master` is your best bet).
 
-### Usage outside of Laravel (since [ff41aae](https://github.com/laravelbook/ardent/commit/ff41aae645e38f21c0b5b9ee542a66ecc25f06a0))
+### Usage outside of Laravel (since [1.1](https://github.com/laravelbook/ardent/tree/v1.1.0))
 
 If you're willing to use Ardent as a standalone ORM package you're invited to do so by using the
 following configuration line in your project's boot/startup file (changing the properties according
@@ -48,9 +48,10 @@ to your database, obviously):
 * [Effortless Validation with Ardent](#validation)
 * [Retrieving Validation Errors](#errors)
 * [Overriding Validation](#override)
-* [Model hooks](#modelhooks)
 * [Custom Validation Error Messages](#messages)
 * [Custom Validation Rules](#rules)
+* [Model hooks](#modelhooks)
+* [Cleaner definition of relationships](#relations)
 * [Automatically Hydrate Ardent Entities](#hydra)
 * [Automatically Purge Redundant Form Data](#purge)
 * [Automatically Transform Secure-Text Attributes](#secure)
@@ -189,8 +190,61 @@ An array that is **not empty** will override the rules or custom error messages
 
 > **Note:** the default value for `$rules` and `$customMessages` is empty `array()`; thus, if you pass an `array()` nothing will be overriden.
 
+<a name="messages"></a>
+## Custom Error Messages
+
+Just like the Laravel Validator, Ardent lets you set custom error messages using the [same sytax](http://doc.laravelbook.com/validation/#custom-error-messages).
+
+```php
+class User extends \LaravelBook\Ardent\Ardent {
+  public static $customMessages = array(
+    'required' => 'The :attribute field is required.',
+    ...
+  );
+}
+```
+
+<a name="rules"></a>
+## Custom Validation Rules
+
+You can create custom validation rules the [same way](http://doc.laravelbook.com/validation/#custom-validation-rules) you would for the Laravel Validator.
+
+<a name="hydra"></a>
+## Automatically Hydrate Ardent Entities
+
+Ardent is capable of hydrating your entity model class from the form input submission automatically! 
+
+Let's see it action. Consider this snippet of code:
+
+```php
+$user           = new User;
+$user->name     = Input::get('name');
+$user->email    = Input::get('email');
+$user->password = Hash::make(Input::get('password'));
+$user->save();
+```
+
+Let's invoke the *magick* of Ardent and rewrite the previous snippet:
+
+```php
+$user = new User;
+$user->save();
+```
+
+That's it! All we've done is remove the boring stuff.
+
+Believe it or not, the code above performs essentially the same task as its older, albeit rather verbose sibling. Ardent populates the model object with attributes from user submitted form data (it uses the Laravel `Input::all()` method internally). No more hair-pulling trying to find out which Eloquent property you've forgotten to populate. Let Ardent take care of the boring stuff, while you get on with the fun stuffs!
+
+To enable the auto-hydration feature, simply set the `$autoHydrateEntityFromInput` instance variable to `true` in your model class:
+
+```php
+class User extends \LaravelBook\Ardent\Ardent {
+  public $autoHydrateEntityFromInput = true;
+}
+```
+
 <a name="modelhooks"></a>
-## Model Hooks
+## Model Hooks (since [2.0](https://github.com/laravelbook/ardent/tree/v2.0.0))
 
 Ardent provides some syntatic sugar over Eloquent's model events: traditional model hooks. They are an easy way to hook up additional operations to different moments in your model life. They can be used to do additional clean-up work before deleting an entry, doing automatic fixes after validation occurs or updating related models after an update happens.
 
@@ -219,7 +273,7 @@ class User extends \LaravelBook\Ardent\Ardent {
 }
 ```
 
-### Additionals beforeSave and afterSave
+### Additionals beforeSave and afterSave (since 1.0)
 
 `beforeSave` and `afterSave` can be included at run-time. Simply pass in closures with the model as argument to the `save()` (or `forceSave()`) method.
 
@@ -237,58 +291,44 @@ $user->save(array(), array(),
 
 > **Note:** the closures should have one parameter as it will be passed a reference to the model being saved.
 
-<a name="messages"></a>
-## Custom Error Messages
+<a name="relations"></a>
+## Cleaner definition of relationships  (since [2.0](https://github.com/laravelbook/ardent/tree/v2.0.0))
 
-Just like the Laravel Validator, Ardent lets you set custom error messages using the [same sytax](http://doc.laravelbook.com/validation/#custom-error-messages).
+Have you ever written an Eloquent model with a bunch of relations, just to notice how cluttered your class is, with all those one-liners that have almost the same content as the method name itself?
+
+In Ardent you can cleanly define your relationships in an array with their information, and they will work just like if you had defined they in methods. Here's an example:
 
 ```php
 class User extends \LaravelBook\Ardent\Ardent {
-  public static $customMessages = array(
-    'required' => 'The :attribute field is required.',
-    ...
+  public static $relationsData = array(
+    'address' => array(self::HAS_ONE, 'Address'),
+    'orders'  => array(self::HAS_MANY, 'Order'),
+    'groups'  => array(self::BELONGS_TO_MANY, 'Group', 'table' => 'groups_have_users')
   );
 }
-```
-
-<a name="rules"></a>
-## Custom Validation Rules
-
-You can create custom validation rules the [same way](http://doc.laravelbook.com/validation/#custom-validation-rules) you would for the Laravel Validator.
-
-<a name="hydra"></a>
-## Automatically Hydrate Ardent Entities
-
-Ardent is capable of hydrating your entity model class from the form input submission automatically! 
-
-Let's see it action. Consider this snippet of code:
 
-```php
-$user           = new User;
-$user->name     = Input::get('name');
-$user->email    = Input::get('email');
-$user->password = Hash::make(Input::get('password'));
-$user->save();
-```
-
-Let's invoke the *magick* of Ardent and rewrite the previous snippet:
-
-```php
-$user = new User;
-$user->save();
+$user = User::find($id);
+echo "{$user->address->street}, {$user->address->city} - {$user->address->state}";
 ```
 
-That's it! All we've done is remove the boring stuff.
-
-Believe it or not, the code above performs essentially the same task as its older, albeit rather verbose sibling. Ardent populates the model object with attributes from user submitted form data (it uses the Laravel `Input::all()` method internally). No more hair-pulling trying to find out which Eloquent property you've forgotten to populate. Let Ardent take care of the boring stuff, while you get on with the fun stuffs!
-
-To enable the auto-hydration feature, simply set the `$autoHydrateEntityFromInput` instance variable to `true` in your model class:
-
-```php
-class User extends \LaravelBook\Ardent\Ardent {
-  public $autoHydrateEntityFromInput = true;
-}
-```
+The array syntax is as follows:
+
+- First indexed value: relation name, being one of
+[`hasOne`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_hasOne),
+[`hasMany`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_hasMany),
+[`belongsTo`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_belongsTo),
+[`belongsToMany`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_belongsToMany),
+[`morphTo`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_morphTo),
+[`morphOne`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_morphOne),
+[`morphMany`](http://laravel.com/api/class-Illuminate.Database.Eloquent.Model.html#_morphMany),
+or one of the related constants (`Ardent::HAS_MANY` or `Ardent::MORPH_ONE` for example).
+- Second indexed: class name, with complete namespace. The exception is `morphTo` relations, that take no additional argument.
+- named arguments, following the ones defined for the original Eloquent methods:
+    - `foreignKey` [optional], valid for `hasOne`, `hasMany`, `belongsTo` and `belongsToMany`
+    - `table` and `otherKey` [optional], valid for `belongsToMany`
+    - `name`, `type` and `id`, used by `morphTo`, `morphOne` and `morphMany` (the last two requires `name` to be defined)
+    
+> **Note:** This feature was based on the easy [relations on Yii 1.1 ActiveRecord](http://www.yiiframework.com/doc/guide/1.1/en/database.arr#declaring-relationship).
 
 <a name="purge"></a>
 ## Automatically Purge Redundant Form Data