Merge pull request #347 from JustinEldracher/master

Made a few changes to the documentation

Author: avbdr

dbObject.md

@@ -1,64 +1,66 @@
-dbObject - model implementation on top of the MysqliDb
-Please note, that this library is not pretending to be a full stack ORM but a simple OOP wrapper for mysqlidb
+dbObject - model implementation on top of the MysqliDb.
+
+Please note that this library is not pretending to be a full stack ORM, but simply an OOP wrapper for `mysqlidb`.
 
 <hr>
 ###Initialization
 
-Include mysqlidb and dbObject classes. If you want to use model autoloading instead of manually including them in the scripts use autoload () method.
+Include mysqlidb and dbObject classes. If you want to use model autoloading instead of manually including them in the scripts use `autoload()` method.
 ```php
-require_once ("libs/MysqliDb.php");
-require_once ("libs/dbObject.php");
+require_once("libs/MysqliDb.php");
+require_once("libs/dbObject.php");
 
 // db instance
-$db = new Mysqlidb ('localhost', 'user', '', 'testdb');
+$db = new Mysqlidb('localhost', 'user', '', 'testdb');
 // enable class autoloading
-dbObject::autoload ("models");
+dbObject::autoload("models");
 ```
 
-Each database table could be easily mapped into a dbObject instance.  If you do not want to create model for a simple table its object could be simply created with a table() method.
+Each database table could be easily mapped into a dbObject instance.  If you do not want to create model for a simple table its object could be simply created with a `table()` method.
 ```php
-$user = dbObject::table ("users");
+$user = dbObject::table("users");
 ```
 
-Otherwise basic model should be declared as (in case if autoload is set to 'models' directory filename should be models/user.php):
+Otherwise basic model should be declared as:
 ```php
 class user extends dbObject {}
 ```
+In case autoload is set to 'models' directory, the filename should be models/user.php
 
-Class will be related to 'user' table. To change table name define correct name in the $dbTable variable:
+Class will be related to 'user' table. To change the table name, define correct name in the `$dbTable` variable:
 
 ```php
     protected $dbTable = "users";
 ```
 
-Both objects created throw new class file creation of with table() method will have the same set of methods available. Only exception is that relations, validation or custom model methods
-will not be working with an objects created with table() method.
+Both objects created throw new class file creation of with `table()` method will have the same set of methods available. Only exception is that relations, validation or custom model methods
+will not be working with an objects created with `table()` method.
 
 
 ###Selects
-Retrieving objects from the database is pretty much the same process as a mysqliDb get()/getOne() methods without a need to specify table name. All mysqlidb functions like where(), orWhere(), orderBy(), join etc are supported.
+Retrieving objects from the database is pretty much the same process as a mysqliDb `get()`/`getOne()` methods without a need to specify table name. All mysqlidb functions like `where()`, `orWhere()`, `orderBy()`, `join()`, etc. are supported.
 
 ##Retrieving All Records
 
 ```php
-//$users = dbObject::table('users')->get ();
-$users = user::get ();
+//$users = dbObject::table('users')->get();
+$users = user::get();
 foreach (users as $u) {
   echo $u->login;
 }
 ```
 
 ## Using Where Condition And A Limit
 ```php
-$users = user::where ("login", "demo")->get (Array (10, 20));
+$users = user::where("login", "demo")->get(Array (10, 20));
 foreach (users as $u) ...
 ```
 
 ##Retrieving A Model By Primary Key
 
 ```php
-//$user = dbObject::table('users')->byId (1);
-$user = user::byId (1);
+//$user = dbObject::table('users')->byId(1);
+$user = user::byId(1);
 echo $user->login;
 ```
 
@@ -70,26 +72,26 @@ dbObject will also assume that each table has a primary key column named "id". Y
 
 
 ###Insert Row
-1. OOP Way. Just create new object of a needed class, fill it in and call save () method. Save will return
+1. OOP Way. Just create new object of a needed class, fill it in and call `save()` method. Save will return
 record id in case of success and false in case if insert will fail.
 ```php
 //$user = dbObject::table('users');
 $user = new user;
 $user->login = 'demo';
 $user->password = 'demo';
-$id = $user->save ();
+$id = $user->save();
 if ($id)
   echo "user created with id = " . $id;
 ```
 
 2. Using arrays
 ```php
-$data = Array ('login' => 'demo',
+$data = Array('login' => 'demo',
         'password' => 'demo');
 $user = new user ($data);
-$id = $user->save ();
+$id = $user->save();
 if ($id == null) {
-    print_r ($user->errors);
+    print_r($user->errors);
     echo $db->getLastError;
 } else
     echo "user created with id = " . $id;
@@ -106,71 +108,71 @@ $p = new product;
 $p->title = "Apples";
 $p->price = 0.5;
 $p->seller = $user;
-$p->save ();
+$p->save();
 ```
 
-After save() is called both new objects (user and product) will be saved.
+After `save()` is called, both new objects (user and product) will be saved.
 
 
 ###Update
-To update model properties just set them and call save () method. As well values that needed to by changed could be passed as an array to the save () method.
+To update model properties just set them and call `save()` method. Values that need to be changed could be passed as an array to the `save()` method as well.
 
 ```php
-$user = user::byId (1);
+$user = user::byId(1);
 $user->password = 'demo2';
-$user->save ();
+$user->save();
 ```
 ```php
-$data = Array ('password', 'demo2');
-$user = user::byId (1);
-$user->save ($data);
+$data = Array('password', 'demo2');
+$user = user::byId(1);
+$user->save($data);
 ```
 
 ###Delete
-Use delete() method on any loaded object.
+Use `delete()` method on any loaded object.
 ```php
-$user = user::byId (1);
-$user->delete ();
+$user = user::byId(1);
+$user->delete();
 ```
 
 ###Relations
-Currently dbObject supports only hasMany and hasOne relations. To use them declare $relations array in the model class.
+Currently dbObject supports only `hasMany` and `hasOne` relations. To use them declare `$relations` array in the model class.
 After that you can get related object via variable names defined as keys.
 
-##HasOne example:
+##hasOne example:
 ```php
-    protected $relations = Array (
-        'person' => Array ("hasOne", "person", 'id');
+    protected $relations = Array(
+        'person' => Array("hasOne", "person", 'id');
     );
 
     ...
 
-    $user = user::byId (1);
+    $user = user::byId(1);
     // sql: select * from users where id = $personValue
     echo $user->person->firstName . " " . $user->person->lastName . " have the following products:\n";
     // one more sql: select * from person where id=x
 ```
 Please note, that following way of querying will execute 2 sql queries:
-1. select * from users where id=1;
-2. select * from person where id=x
+1. `select * from users where id=1`
+2. `select * from person where id=x`
 
-To optimize this into single select join query use with() method.
+To optimize this into single select join query use `with()` method.
 ```php
-   $user = user::with ('person')->byId (1);
+   $user = user::with('person')->byId(1);
    // sql: select * from users left join person on person.id = users.id wher id = 1;
     echo $user->person->firstName . " " . $user->person->lastName . " have the following products:\n";
 ```
 
-##HasMany example:
-In HasMany Array should be defined target object name (product in example) and a relation key (userid).
+##hasMany example:
+In the `hasMany` array should be defined the target object name (product in example) and a relation key (userid).
 ```php
-    protected $relations = Array (
-        'products' => Array ("hasMany", "product", 'userid')
+    protected $relations = Array(
+        'products' => Array("hasMany", "product", 'userid')
     );
 
     ...
 
-    $user = user::byId (1);
+    $user = user::byId(1);
     // sql: select * from $product_table where userid = $userPrimaryKey
     foreach ($user->products as $p) {
             echo $p->title;
@@ -179,110 +181,108 @@ In HasMany Array should be defined target object name (product in example) and a
 
 ### Joining tables
 ```php
-$depts = product::join ('user');
-$depts = product::join ('user', 'productid');
+$depts = product::join('user');
+$depts = product::join('user', 'productid');
 ```
 
-First parameter will set an object which should be joined. Second paramter will define a key. Default key is $objectName+'Id'
+First parameter will set an object which should be joined. Second paramter will define a key. Default key is `$objectName+'Id'`
 
 
-NOTE: Objects returned with join() will not save changes to a joined properties. For this you can use relationships.
+NOTE: Objects returned with `join()` will not save changes to a joined properties. For this you can use relationships.
 
 ###Timestamps
 Library provides a transparent way to set timestamps of an object creation and its modification:
-To enable that define $timestamps array as follows:
+To enable that define `$timestamps` array as follows:
 ```php
 protected $timestamps = Array ('createdAt', 'updatedAt');
 ```
-Field names cant be changed.
+Field names can't be changed.
 
-### Array Fields
-dbObject can automatically handle array type of values. Optionaly you can store arrays in json encoded or in pipe delimeted format.
-To enable automatic json serialization of the field define $jsonFields array in your modal:
+###Array Fields
+dbObject can automatically handle array type of values. Optionaly you can store arrays in json encoded or in pipe delimited format.
+To enable automatic json serialization of the field define `$jsonFields` array in your modal:
 ```php
-    protected $jsonFields = Array ('operations');
+    protected $jsonFields = Array('options');
 ```
-To enable pipe delimetered storage of the field define $arrayFields array in your modal:
+To enable pipe delimited storage of the field, define `$arrayFields` array in your modal:
 ```php
-    protected $arrayFields = Array ('sections');
+    protected $arrayFields = Array('sections');
 ```
-
+The following code will now store `'options'` variable as a json string in the database, and will return an array on load.
+Same with the `'sections'` variable except that it will be stored in pipe delimited format.
 ```php
     $user = new user;
     $user->login = 'admin';
-    $user->options = Array ('canReadNews', 'canPostNews', 'canDeleteNews');
-    $user->sections = Array ('news', 'companyNews');
-    $user->save ();
+    $user->options = Array('canReadNews', 'canPostNews', 'canDeleteNews');
+    $user->sections = Array('news', 'companyNews');
+    $user->save();
     ...
-    $user = user::byId (1);
-    print_r ($user->options);
+    $user = user::byId(1);
+    print_r($user->options);
 ```
-Following code will store 'options' variable as a json string in the database and will return back an array on load.
-Same with 'sections' variable except that it will be stored in pipe delimetered format.
-
 
 ###Validation and Error checking
-Before saving and updating the row dbObject do input validation. In case validation rules are set but their criteria is not met
-then save() will return an error with its description. For example:
+Before saving and updating the row, dbObject does input validation. In case validation rules are set but their criteria is
+not met, then `save()` will return an error with its description. For example:
 ```php
 $id = $user->save();
 if (!$id) {
     // show all validation errors
-    print_r ($user->errors);
+    print_r($user->errors);
     echo $db->getLastQuery();
     echo $db->getLastError();
 }
 echo "user were created with id" . $id;
 ```
-Validation rules must be defined in $dbFields array.
+Validation rules must be defined in `$dbFields` array.
 ```php
-  protected $dbFields = Array (
-    'login' => Array ('text', 'required'),
-    'password' => Array ('text'),
-    'createdAt' => Array ('datetime'),
-    'updatedAt' => Array ('datetime'),
-    'custom' => Array ('/^test/'),
+  protected $dbFields = Array(
+    'login' => Array('text', 'required'),
+    'password' => Array('text'),
+    'createdAt' => Array('datetime'),
+    'updatedAt' => Array('datetime'),
+    'custom' => Array('/^test/'),
   );
 ```
 First parameter is a field type. Types could be the one of following: text, bool, int, datetime or a custom regexp.
 Second parameter is 'required' and its defines that following entry field be always defined.
 
-NOTE: All variables which are not defined in the $dbFields array will be ignored from insert/update statement.
+**NOTE:** All variables which are not defined in the `$dbFields` array will be ignored from insert/update statement.
 
 ###Using array as a return value
-dbObject can return its data as array instead of object. To do that ArrayBuilder() function should be used in the beginning of the call.
+dbObject can return its data as array instead of object. To do that, the `ArrayBuilder()` function should be used in the beginning of the call.
 ```php
-    $user = user::ArrayBuilder()->byId (1);
+    $user = user::ArrayBuilder()->byId(1);
     echo $user['login'];
 
-    $users = user::ArrayBuilder()->orderBy ("id", "desc")->get ();
+    $users = user::ArrayBuilder()->orderBy("id", "desc")->get();
     foreach ($users as $u)
         echo $u['login'];
 ```
 
-Following call will return data only of the called instance without any relations data. Use with() function to include relation data as well.
+The following call will return data only of the called instance without any relations data. Use `with()` function to include relation data as well.
 ```php
-    $user = user::ArrayBuilder()->with ("product")->byId (1);
+    $user = user::ArrayBuilder()->with("product")->byId(1);
     print_r ($user['products']);
 ```
 
 ###Using json as a return value
-Togeather with ArrayBuilder() and ObjectBuilder() dbObject can return result in json format to avoid extra coding
+Together with `ArrayBuilder()` and `ObjectBuilder()`, dbObject can also return a result in json format to avoid extra coding.
 ```php
-    $userjson = user::JsonBuilder()->with ("product")->byId (1);
+    $userjson = user::JsonBuilder()->with("product")->byId(1);
 ```
 ###Object serialization
 
 Object could be easily converted to a json string or an array.
 
 ```php
-    $user = user::byId (1);
+    $user = user::byId(1);
     // echo will display json representation of an object
     echo $user;
     // userJson will contain json representation of an object
-    $userJson = $user->toJson ();
+    $userJson = $user->toJson();
     // userArray will contain array representation of an object
-    $userArray = $user->toArray ();
+    $userArray = $user->toArray();
 ```
 
 ###Examples