diff --git a/README.md b/README.md index 3f45f85..a45428b 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,28 @@ SafeMySQL ========= -SafeMySQL is a PHP class for safe and convenient handling of Mysql queries. -- safe because every dynamic query part goes into query via placeholder -- convenient because it makes application code short and meaningful, without useless repetitions, making it Extra DRY +SafeMySQL is a PHP class for safe and convenient handling of MySQL queries. +- Safe because every dynamic query part goes into the query via placeholder +- Convenient because it makes application code short and meaningful, without useless repetitions, making it ''extra'' DRY This class is distinguished by three main features -- unlike standard libraries, it is using **type-hinted placeholders**, for the **everything** that may be put into query -- unlike standard libraries, it require no repetitive binding, fetching and such, +- Unlike standard libraries, it is using **type-hinted placeholders**, for the **everything** that may be put into the query +- Unlike standard libraries, it require no repetitive binding, fetching and such, thanks to set of helper methods to get the desired result right out of the query -- unlike standard libraries, it can parse placeholders not in the whole query only, but in the arbitary query part, +- Unlike standard libraries, it can parse placeholders not in the whole query only, but in the arbitary query part, thanks to indispensabe **parse()** method, making complex queries as easy and safe as regular ones. -Yet it is very easy to use. You need to learn only few things: +Yet it is very easy to use. You need to learn only a 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: +1. You have to **always** pass whatever dynamical data into the query via *placeholder* +2. Each placeholder have to be marked with data type. At the moment there are six 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. To get data right out of the query there are helper methods for the most used : +3. To get data right out of the query there are helper methods for the most used: * query($query,$param1,$param2, ...) - returns mysqli resource. * getOne($query,$param1,$param2, ...) - returns scalar value * getRow($query,$param1,$param2, ...) - returns 1-dimensional array, a row @@ -39,16 +39,16 @@ The rest is as usual - just create a regular SQL (with placeholders) and get a r * ```$data = $db->getAll("SELECT * FROM ?n WHERE mod=?s LIMIT ?i",$table,$mod,$limit);``` The main feature of this class is a type-hinted placeholders. -And it's really great step further from just ordinal placeholders used in prepared statements. +And it's a really great step further from just ordinal placeholders used in prepared statements. Simply because dynamical parts of the query aren't limited to just scalar data! -In the real life we have to add identifiers, arrays for ```IN``` operator, arrays for ```INSERT``` and ```UPDATE``` queries. +In the real life we have to add identifiers, arrays for ```IN``` operator, and arrays for ```INSERT``` and ```UPDATE``` queries. So - we need many 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: +Look at all the questions on Stack Overflow where developers are trying in vain to bind a field name. +Voila - with the identifier placeholder it is as easy as adding a field value: ```php $field = $_POST['field']; @@ -62,14 +62,14 @@ 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: +Another trouble in creating prepared queries - arrays going to the IN operator. Everyone is trying to do it their own way, but the type-hinted placeholder makes it as simple as adding a string: ```php $array = array(1,2,3); $data = $db->query("SELECT * FROM table WHERE id IN (?a)",$array); ``` -Same goes for such toilsome queries like ```INSERT``` and ```UPDATE```. +The 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. +And, of course, we have a set of helper functions to turn type-hinted placeholders into real brilliant, making almost every call to the database as simple as one or two lines of code for all the regular real life tasks.