SafeMySql/README.md

SafeMySQL
=========

SafeMySQL is a PHP class for safe and convenient handling of Mysql queries.
- safe because <b>every</b> dynamic query part goes into query via <b>placeholder</b>
- convenient because it makes application code short and meaningful, without useless repetitions, making it Extra <abbr title="Don't Repeat Yourself">DRY</abbr>

This class is distinguished by three main features
- type-hinted placeholders
- set of helper methods to get the desired result right out of query
- indispensabe **parse()** method which allows to parse placeholders not in the whole query only (like with native prepared statements) but in the arbitary query part

Yet it is very easy to use. You need to learn only few things:

1. You have to **always** pass whatever dynamical data into query via *placeholder*
2. Each placeholder have to be marked with data type. At the moment there are 6 types:
 * ?s ("string")  - strings (also DATE, FLOAT and DECIMAL)
 * ?i ("integer") - the name says it all 
 * ?n ("name")    - identifiers (table and field names) 
 * ?a ("array")   - complex placeholder for IN() operator  (substituted with string of 'a','b','c' format, without parentesis)
 * ?u ("update")  - complex placeholder for SET operator (substituted with string of `field`='value',`field`='value' format)
 * ?p ("parsed")  - special type placeholder, for inserting already parsed statements without any processing, to avoid double parsing.
3. **No need** for the repetitive binding, fetching and such. Get desired result in the proper format already:
 * query($query,$param1,$param2, ...) - returns mysqli resource.
 * getOne($query,$param1,$param2, ...) - returns scalar value
 * getRow($query,$param1,$param2, ...) - returns 1-dimensional array, a row
 * getCol($query,$param1,$param2, ...) - returns 1-dimensional array, a column
 * getAll($query,$param1,$param2, ...) - returns 2-dimensional array, an array of rows
 * getInd($key,$query,$par1,$par2, ...) - returns an indexed 2-dimensional array, an array of rows
 * getIndCol($key,$query,$par1,$par2, ...) - returns 1-dimensional array, an indexed column, consists of key => value pairs
4. For the whatever complex case always use **parse()** method. And insert already parsed parts via **?p** placeholder

The rest is as usual - just create a usual SQL (with placeholders) and get a result.

The main feature of this class is a <i>type-hinted placeholders</i>. 
And it's really great step further from just ordinal placeholders used in prepared statements. 
Simply because <b>dynamical parts of the query aren't limited to just scalar data!</b>
In the real life we have to add identifiers, arrays for IN operator, arrays for INSERT and UPDATE queries.
So - we need <b>many</b> different types of data formatting. Thus, we need the way to tell the driver how to format this particular data. 
Conventional prepared statements use toilsome and repeating bind_* functions. 
But there is a way more sleek and useful way - to set the type along with placeholder itself. It is not something new - well-known printf() function uses exactly the same mechanism. So, I hesitated not to borrow such a brilliant idea.

To implement such a feature, no doubt one have to have their own query parser. No problem, it's not a big deal. But the benefits are innumerable. 
Look at all the questions on Stackoverflow where developers trying in vain to bind a field name.
Voila - with identifier placeholder it is as easy as adding a field value:

<code>
$field = $_POST['field'];<br>
$value = $_POST['value'];<br>
$sql   = "SELECT * FROM table WHERE ?n LIKE ?s";<br>
$data  = $db->query($sql,$field,"%$value%");</code>

Nothing could be easier!

Of course we will have placeholders for the common types - strings and numbers.
But as we started inventing new placeholders - let's make some more!

Another trouble in creating prepared queries - arrays going to IN operator. Everyone is trying to do it their own way but the type-hinted placeholder makes it as simple as adding a string:

<code>
$array = array(1,2,3);<br>
$data  = $db->query("SELECT * FROM table WHERE id IN (?a)",$array);</code>

Same goes for such toilsome queries like INSERT and UPDATE.

And, of course, we have a set of helper functions to turn type-hinted placeholders into real brilliant, making almost every call to database as simple as 1 or 2 lines of code for all the regular real life tasks.