Added raw_where support, documentation and tests

1 files changed, 11 insertions, 1 deletions

diff --git a/README.markdown b/README.markdown
index 02f1932..c85139a 100644
--- a/README.markdown
+++ b/README.markdown
@@ -56,7 +56,7 @@ Idiorm provides a [*fluent interface*](http://en.wikipedia.org/wiki/Fluent_inter
 
 All Idiorm queries start with a call to the `for_table` static method on the ORM class. This tells the ORM which table to use when making the query. Method calls which add parameters to the query are then strung together. Finally, the chain is finished by calling either `find_one()` or `find_many()`, which executes the query and returns the result.
 
-Let's start with a simple example. Say we have a table called `person` which contains the columns `id` (the primary key of the record - Idiorm assumes the primary key column is called `id` but this is configurable, see below [TODO]), `name`, `age` and `gender`.
+Let's start with a simple example. Say we have a table called `person` which contains the columns `id` (the primary key of the record - Idiorm assumes the primary key column is called `id` but this is configurable, see below), `name`, `age` and `gender`.
 
 #### Single records ####
 
@@ -90,6 +90,16 @@ The `where` method on the ORM class adds a single `WHERE` clause to your query.
 
 By default, calling `where` with two parameters (the column name and the value) will combine them using an equals operator (`=`). For example, calling `where('name', 'Fred')` will result in the clause `WHERE name = "Fred"`. However, the `where` method takes an optional third parameter which specifies the type of operator to use. Constants for each operator are provided on the ORM class. Currently, the supported operators are: `ORM::EQUALS` and `ORM::LIKE`.
 
+#### Raw WHERE clauses ####
+
+If you require a more complex query, you can use the `where_raw` method to specify the SQL fragment exactly. This method takes two parameter: the string to add to the query, and an array of parameters which will be bound to the string. The string should contain question marks to represent the values to be bound, and the parameter array should contain the values to be substituted into the string in the correct order.
+
+This method may be chained with other methods such as `offset`, `limit` and `order_by_(*)`, but it may NOT be chained with other calls to `where`. If other `where` clauses are added, they will simply be ignored in the resulting query.
+
+    ORM::for_table('person')->where_raw('name = ? AND (age = ? OR age = ?)', array('Fred', 5, 10))->order_by_asc('name');
+
+Note that this method only supports "question mark placeholder" syntax, and NOT "named placeholder" syntax.
+
 #### LIMIT and OFFSET ####
 
 The `limit` and `offset` methods map pretty closely to their SQL equivalents.