First MagicQuery commit with new MagicQuery class

Author: moufmouf

.gitignore

@@ -0,0 +1 @@
+vendor/

README.md

@@ -1,13 +1,13 @@
-What is QueryWritter?
-=====================
+What is Magic-query?
+====================
 
-QueryWritter is a PHP library that parses SQL queries, transforms those into an object representation, stores them in a 
-dependency injection container, and returns them as string. It is a [Mouf plugin](http://mouf-php.com).
+Magic-query is a PHP library that helps you work with complex queries that require
+a variable number of parameters.
 
-Ok, but why would I use QueryWritter?
--------------------------------------
+Why should I care?
+------------------
 
-Because it is **the most effecient way to deal with queries that can have a variable number of parameters**!
+Because it is **the most efficient way to deal with queries that can have a variable number of parameters**!
 Think about a typical datagrid with a bunch of filter (for instance a list of products filtered by name, company, price, ...).
 If you have the very common idea to generate the SQL query using no PHP library, your code will look like this:
 
@@ -23,50 +23,53 @@ if (isset($params['name'])) {
 if (isset($params['company'])) {
 	$sql .= "AND c.name LIKE '".addslashes($params['company'])."%'";
 }
+if (isset($params['country'])) {
+	$sql .= "AND c.country LIKE '".addslashes($params['country'])."%'";
+}
 // And so on... for each parameter, we have a "if" statement
 ```
 
-
-
-Concatenating SQL queries is dangerous (especially if you forget to protect parameters).
+Concatenating SQL queries is **dangerous** (especially if you forget to protect parameters).
 You can always use parameterized SQL queries, but you will still have to concatenate the filters.
 
 To avoid concatenating strings, frameworks and libraries have used different strategies. Building a full ORM (like
 Doctrine or Propel) is a good idea, but it makes writing complex queries even more complex. Other frameworks like
 Zend are building queries using function calls. These are valid strategies, but you are no more typing SQL queries
 directly, and let's face it, it is always useful to use a query directly.
 
-This is where QueryWritter becomes helpful.
+This is where Magic-query becomes helpful.
 
 How does it work?
 -----------------
-// TODO: schema... or even better... video!
-
-###1- Write your query
-You start by writing your query, **in plain SQL**. No ORM, no special query language (DQL or HQL anyone?), just plain and simple SQL.
-This is cool because everybody knows SQL. In your query, you put absolutely all the parameters you can imagine.
-
-###2- Store your query in Mouf
-In Mouf UI, go to **DB** > **SQL queries** > **Create SQL query**.
-Here, you can **copy and paste your query**. Since this is Mouf, every query is an "instance", and you have to pick
-a name for your query. 
 
-Behind the scenes, QueryWritter will parse your query and make sure every piece of the query (each table, each column, each filter...) is transformed 
-into an object. But you really don't have to care about that right now.
+Easy! You write the query with all possible parameters.
 
-###3- Test your query
-Right from Mouf UI, you can test your query! And lo and behold! Because the query was parsed, **QueryWritter will dynamically 
-add parts of the query depending on the parameters you decide to use**.
-
-###4- Use it in your code
-If you are not a Mouf user (if you are using Drupal, Symfony, Zend Framework...), you can directly use the query by fetching the instance from Mouf and calling the <code>toSql</code> method, passing 
-parameters in... parameter :)
-
-```
-$mySelect = Mouf::getMySelectStatement();
-$sql = $mySelect->toSql(array("status"=>1, "search"=>"hello"));
+```php
+$sql = "SELECT * FROM
+		products p JOIN companies c
+			ON p.company_id = c.id
+	WHERE
+		p.name LIKE :name
+		AND c.name LIKE :company
+		AND c.country LIKE :country";
+
+// Get a MagicQuery object.
+$magicQuery = new MagicQuery();
+
+// Here, we pass only the "name" parameter
+$generatedSql = $magicQuery->build($sql, [ "name" => "%John%" ]);
+// $generatedSql will not include the "c.name" filter!
+
+// Here we pass no parameters
+$generatedSql2 = $magicQuery->build($sql, []);
+// The WHERE statement will be completely removed!
 ```
 
-If you are a Mouf user, you can even directly run the query using the **QueryResult** class that executes
-the query directly. Or even better, use the **Evolugrid** module, and display your query result in an HTML
-datagrid, directly!
+How does it work under the hood?
+--------------------------------
+
+A lot happens to your SQL query. It is actually parsed (thanks to a modified
+	version of the php-sql-parser library) and then changed into a tree.
+	The magic happens on the tree where the node containing unused parameters
+	are simply discarded. When it's done, the tree is changed back to SQL and
+	"shazam!", your SQL query is purged of useless parameters!

composer.json

@@ -1,9 +1,9 @@
 {
-    "name": "mouf/database.querywriter",
-    "description": "This package contains classes useful to generate SQL statements such as SELECT queries, etc...",
+    "name": "mouf/magic-query",
+    "description": "A very clever library to generate PHP prepared statement with a variable number of parameters... and much more!",
     "keywords": ["database", "query", "mouf"],
-    "homepage": "https://github.com/thecodingmachine/database.querywriter",
-    "type": "mouf-library",
+    "homepage": "http://mouf-php.com/packages/mouf/magic-query",
+    "type": "library",
     "license": "MIT",
     "authors": [
         {
@@ -14,25 +14,35 @@
     ],
     "require": {
     	"php": ">=5.3.0",
-    	"mouf/database.doctrine-dbal-wrapper": "~1.1",
     	"mouf/utils.common.conditioninterface": "~2.0",
     	"mouf/utils.value.value-interface": "~1.0",
     	"mouf/utils.common.paginable-interface": "~1.0",
-    	"mouf/utils.common.sortable-interface": "~1.0",
-        "mouf/html.widgets.evolugrid": "~3.0"
+    	"mouf/utils.common.sortable-interface": "~1.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "~4.0"
+    },
+    "suggest": {
+      "doctrine/dbal": "To support more databases than just MySQL",
+      "mouf/database.querywriter": "To get a nice user interface to edit your SQL queries",
+      "mouf/mouf": "To get a nice user interface to edit your SQL queries"
     },
     "autoload": {
-        "psr-0": {
-            "Mouf\\Database\\QueryWriter": "src/",
-            "SQLParser": "src/"
+        "psr-4": {
+            "Mouf\\Database\\": "src/Mouf/Database/",
+            "SQLParser\\": "src/SQLParser/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Mouf\\Database\\": "tests/Mouf/Database/"
         }
     },
     "extra": {
-	     "mouf": {
-	         "require-admin": [
-    			"src/QueryWriterAdmin.php"
-    			],
+        "mouf": {
 			"logo": "database.png"
 		}
-	}
+	},
+    "minimum-stability": "dev",
+    "prefer-stable": true
 }

icons/database_go.png

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit backupGlobals="false"
+         backupStaticAttributes="false"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         syntaxCheck="false"
+         bootstrap="tests/bootstrap.php"
+>
+    <testsuites>
+        <testsuite name="Mouf Test Suite">
+            <directory>./tests/</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

icons/database_query.png

@@ -0,0 +1,43 @@
+<?php
+namespace Mouf\Database;
+use SQLParser\Query\StatementFactory;
+use SQLParser\SQLParser;
+use SQLParser\SqlRenderInterface;
+
+/**
+ * The class MagicQuery offers special SQL voodoo methods to automatically strip down unused parameters
+ * from parameterized SQL statements.
+ */
+class MagicQuery
+{
+    private $connection;
+
+    /**
+     * @param Doctrine\DBAL\Connection $connection
+     */
+    public function __construct($connection = null) {
+        $this->connection = $connection;
+    }
+
+    /**
+     * Returns merged SQL from $sql and $parameters. Any parameters not available will be striped down
+     * from the SQL.
+     *
+     * @param string $sql
+     * @param array $parameters
+     * @return string
+     */
+    public function build($sql, array $parameters = array()) {
+        $parser = new SQLParser();
+        $parsed = $parser->parse($sql);
+
+        if ($parsed == false) {
+            throw new MagicQueryParserException('Unable to parse query "'.$sql.'"');
+        }
+
+        $select = StatementFactory::toObject($parsed);
+
+        $sql = $select->toSql($parameters, $this->connection, 0, SqlRenderInterface::CONDITION_GUESS);
+        return $sql;
+    }
+}

phpunit.xml.dist

@@ -0,0 +1,8 @@
+<?php
+namespace Mouf\Database;
+
+
+class MagicQueryParserException extends \Exception
+{
+
+}