Merge pull request #6 from moufmouf/twig

Twig integration

Author: Marc TEYSSIER

README.md

@@ -14,6 +14,7 @@ It comes with 2 great features:
 
 - [**MagicParameters**: it helps you work with SQL queries that require a variable number of parameters.](#parameters)
 - [**MagicJoin**: it writes JOINs for you!](#joins)
+- [**MagicTwig**: use Twig templating in your SQL queries](#twig)
 
 Installation
 ------------
@@ -106,6 +107,62 @@ $completeSql = $magicQuery->build($sql);
 
 Want to know more? <a class="btn btn-primary btn-large" href="doc/magic_join.md">Check out the MagicJoin guide!</a>
 
+<a name="twig"></a>
+Use Twig templating in your SQL queries!
+----------------------------------------
+
+Discarding unused parameters and auto-joining keys is not enough? You have very specific needs? Say hello to 
+Twig integration!
+
+Using Twig integration, you can directly add Twig conditions right into your SQL.
+
+```php
+use Mouf\Database\MagicQuery;
+
+$sql = "SELECT users.* FROM users {% if isAdmin %} WHERE users.admin = 1 {% endif %}";
+
+$magicQuery = new MagicQuery();
+// By default, Twig integration is disabled. You need to enable it.
+$magicQuery->setEnableTwig(true);
+
+$completeSql = $magicQuery->build($sql, ['isAdmin' => true]);
+// Parameters are passed to the Twig SQL query, and the SQL query is returned.
+```
+
+<div class="alert alert-info"><strong>Heads up!</strong> The Twig integration cannot be used to insert parameters
+into the SQL query. You should use classic SQL parameters for this. This means that instead if writing 
+<code>{{ id }}</code>, you should write <code>:id</code>.</div>
+
+Want to know more? <a class="btn btn-primary" href="doc/magic_twig.md">Check out the MagicTwig guide!</a>
+
+<a name="twig"></a>
+Use Twig templating in your SQL queries!
+----------------------------------------
+
+Discarding unused parameters and auto-joining keys is not enough? You have very specific needs? Say hello to 
+Twig integration!
+
+Using Twig integration, you can directly add Twig conditions right into your SQL.
+
+```php
+use Mouf\Database\MagicQuery;
+
+$sql = "SELECT users.* FROM users {% if isAdmin %} WHERE users.admin = 1 {% endif %}";
+
+$magicQuery = new MagicQuery();
+// By default, Twig integration is disabled. You need to enable it.
+$magicQuery->setEnableTwig(true);
+
+$completeSql = $magicQuery->build($sql, ['isAdmin' => true]);
+// Parameters are passed to the Twig SQL query, and the SQL query is returned.
+```
+
+<div class="alert alert-info"><strong>Heads up!</strong> The Twig integration cannot be used to insert parameters
+into the SQL query. You should use classic SQL parameters for this. This means that instead if writing 
+<code>{{ id }}</code>, you should write <code>:id</code>.</div>
+
+Want to know more? <a class="btn btn-primary" href="doc/magic_twig.md">Check out the MagicTwig guide!</a>
+
 Is it a MySQL only tool?
 ------------------------
 

composer.json

@@ -18,7 +18,8 @@
     	"mouf/utils.value.value-interface": "~1.0",
     	"mouf/utils.common.paginable-interface": "~1.0",
     	"mouf/utils.common.sortable-interface": "~1.0",
-        "mouf/schema-analyzer": "~1.0"
+        "mouf/schema-analyzer": "~1.0",
+        "twig/twig": "~1.14"
     },
     "require-dev": {
         "phpunit/phpunit": "~4.0",

doc/discard_unused_parameters.md

@@ -65,6 +65,28 @@ $magicQuery = new MagicQuery();
 $sql = $magicQuery->build($sql, $params);
 ```
 
+####Forcing some parameters to be null
+
+MagicQuery assumes that if a parameter is null, you want to completely remove the code related to this 
+parameter from the SQL.
+
+But sometimes, you actually want to test parameters against the NULL value.
+In those cases, you need to disable the MagicParameter feature of MagicQuery for those parameters.
+
+<div class="alert alert-info">To disable MagicParameter for a given parameter, simply add an exclamation
+mark (!) after the parameter name.</div>
+
+```php
+// This query uses twice the "status" parameter. Once with ! and once without
+$sql = "SELECT * FROM products p WHERE status1 = :status AND status2 = :status!";
+
+$magicQuery = new MagicQuery();
+// We don't pass the "status" parameter
+$sql = $magicQuery->build($sql, []);
+// The part "status1 = :status" is discarded, but the part "status2 = :status!" is kept
+// $sql == "SELECT * FROM products p WHERE status2 = null"
+```
+
 ###Other alternatives
 
 To avoid concatenating strings, frameworks and libraries have used different strategies. Using a full ORM (like

doc/magic_twig.md

@@ -0,0 +1,41 @@
+Use Twig templating in your SQL queries!
+----------------------------------------
+
+Using Twig integration, you can directly add Twig conditions right into your SQL.
+
+```php
+use Mouf\Database\MagicQuery;
+
+$sql = "SELECT users.* FROM users {% if isAdmin %} WHERE users.admin = 1 {% endif %}";
+
+$magicQuery = new MagicQuery();
+// By default, Twig integration is disabled. You need to enable it.
+$magicQuery->setEnableTwig(true);
+
+$completeSql = $magicQuery->build($sql, ['isAdmin' => true]);
+// Parameters are passed to the Twig SQL query, and the SQL query is returned.
+```
+
+Limitations
+-----------
+
+<div class="alert alert-info"><strong>Heads up!</strong> The Twig integration cannot be used to insert parameters
+into the SQL query. You should use classic SQL parameters for this. This means that instead if writing 
+<code>{{ id }}</code>, you should write <code>:id</code>.</div>
+
+You cannot directly use Twig parameters because Twig transformation is applied before SQL parsing. If parameters
+where replaced by Twig before SQL is parsed, the caching of the transformation *SQL => parsed SQL* would become
+inefficient.
+
+For this reason, if you try to use `{{ parameter }}` instead of `:parameter` in your SQL query, an exception will
+be thrown.
+
+Usage
+-----
+
+For most queries, we found out that MagicJoin combined to MagicParameters is enough.
+For this reason, MagicTwig is disabled by default. If you want to enable it, you can simply call 
+`$magicQuery->setEnableTwig(true)` before calling the `build` method.
+
+MagicTwig can typically be useful when you have parts of a query that needs to be added conditionally, depending 
+on provided parameters.

phpunit.xml.dist

@@ -11,9 +11,20 @@
          syntaxCheck="false"
          bootstrap="tests/bootstrap.php"
 >
+
+    <php>
+        <var name="db_url" value="mysql://root:@localhost/"/>
+    </php>
+
     <testsuites>
         <testsuite name="Mouf Test Suite">
             <directory>./tests/</directory>
         </testsuite>
     </testsuites>
+
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory suffix=".php">src/</directory>
+        </whitelist>
+    </filter>
 </phpunit>

src/Mouf/Database/MagicQuery.php

@@ -3,6 +3,7 @@
 namespace Mouf\Database;
 
 use Doctrine\Common\Cache\VoidCache;
+use Mouf\Database\MagicQuery\Twig\SqlTwigEnvironmentFactory;
 use Mouf\Database\SchemaAnalyzer\SchemaAnalyzer;
 use SQLParser\Node\ColRef;
 use SQLParser\Node\Equal;
@@ -26,6 +27,11 @@ class MagicQuery
     private $connection;
     private $cache;
     private $schemaAnalyzer;
+    /**
+     * @var \Twig_Environment
+     */
+    private $twigEnvironment;
+    private $enableTwig = false;
 
     /**
      * @param \Doctrine\DBAL\Connection $connection
@@ -45,6 +51,17 @@ public function __construct($connection = null, $cache = null, SchemaAnalyzer $s
         }
     }
 
+    /**
+     * Whether Twig parsing should be enabled or not.
+     * Defaults to false.
+     * @param bool $enableTwig
+     * @return $this
+     */
+    public function setEnableTwig($enableTwig = true) {
+        $this->enableTwig = $enableTwig;
+        return $this;
+    }
+
     /**
      * Returns merged SQL from $sql and $parameters. Any parameters not available will be striped down
      * from the SQL.
@@ -58,6 +75,9 @@ public function __construct($connection = null, $cache = null, SchemaAnalyzer $s
      */
     public function build($sql, array $parameters = array())
     {
+        if ($this->enableTwig) {
+            $sql = $this->getTwigEnvironment()->render($sql, $parameters);
+        }
         $select = $this->parse($sql);
         return $this->toSql($select, $parameters);
     }
@@ -218,4 +238,14 @@ private function getSchemaAnalyzer() {
     private function getConnectionUniqueId() {
         return hash('md4', $this->connection->getHost()."-".$this->connection->getPort()."-".$this->connection->getDatabase()."-".$this->connection->getDriver()->getName());
     }
+
+    /**
+     * @return \Twig_Environment
+     */
+    private function getTwigEnvironment() {
+        if ($this->twigEnvironment === null) {
+            $this->twigEnvironment = SqlTwigEnvironmentFactory::getTwigEnvironment();
+        }
+        return $this->twigEnvironment;
+    }
 }

src/Mouf/Database/MagicQuery/Twig/ForbiddenTwigParameterInSqlException.php

@@ -0,0 +1,9 @@
+<?php
+namespace Mouf\Database\MagicQuery\Twig;
+
+use Mouf\Database\MagicQueryException;
+
+class ForbiddenTwigParameterInSqlException extends MagicQueryException
+{
+
+}

src/Mouf/Database/MagicQuery/Twig/SqlTwigEnvironmentFactory.php

@@ -0,0 +1,57 @@
+<?php
+namespace Mouf\Database\MagicQuery\Twig;
+
+use Doctrine\DBAL\Connection;
+
+/**
+ * Class in charge of creating the Twig environment
+ */
+class SqlTwigEnvironmentFactory
+{
+    private static $twig;
+
+    public static function getTwigEnvironment() {
+        if (self::$twig) {
+            return self::$twig;
+        }
+
+        $stringLoader = new StringLoader();
+
+        $options = array(
+            // The cache directory is in the temporary directory and reproduces the path to the directory (to avoid cache conflict between apps).
+            'cache' => self::getCacheDirectory(),
+            'strict_variables' => true
+        );
+
+        $twig = new \Twig_Environment($stringLoader, $options);
+
+        // Default escaper will throw an exception. This is because we want to use SQL parameters instead of Twig.
+        // This ahs a number of advantages, especially in terms of caching.
+        $twig->getExtension('core')->setEscaper('sql', function() {
+            throw new ForbiddenTwigParameterInSqlException('You cannot use Twig expressions (like "{{ id }}"). Instead, you should use SQL parameters (like ":id"). Twig integration is limited to Twig statements (like "{% for .... %}"');
+        });
+
+        // Default autoescape mode: sql
+        $twig->addExtension(new \Twig_Extension_Escaper('sql'));
+
+        self::$twig = $twig;
+
+        return $twig;
+    }
+
+    private static function getCacheDirectory() {
+        // If we are running on a Unix environment, let's prepend the cache with the user id of the PHP process.
+        // This way, we can avoid rights conflicts.
+
+        // @codeCoverageIgnoreStart
+        if (function_exists('posix_geteuid')) {
+            $posixGetuid = '_'.posix_geteuid();
+        } else {
+            $posixGetuid = '';
+        }
+        // @codeCoverageIgnoreEnd
+        $cacheDirectory = rtrim(sys_get_temp_dir(), '/\\').'/magicquerysqltwigtemplate'.$posixGetuid.str_replace(":", "", __DIR__);
+
+        return $cacheDirectory;
+    }
+}

src/Mouf/Database/MagicQuery/Twig/StringLoader.php

@@ -0,0 +1,36 @@
+<?php
+namespace Mouf\Database\MagicQuery\Twig;
+
+
+/**
+ * This loader completely bypasses the loader mechanism, by directly passing the key as a template.
+ * Useful in our very case.
+ *
+ * This is a reimplementation of Twig's String loader that has been deprecated.
+ * We enable it back in our case because there won't be a million of different cache keys.
+ * And yes, we know what we are doing :)
+ */
+class StringLoader implements \Twig_LoaderInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getSource($name)
+    {
+        return $name;
+    }
+    /**
+     * {@inheritdoc}
+     */
+    public function getCacheKey($name)
+    {
+        return $name;
+    }
+    /**
+     * {@inheritdoc}
+     */
+    public function isFresh($name, $time)
+    {
+        return true;
+    }
+}

src/SQLParser/Node/AbstractTwoOperandsOperator.php

@@ -101,12 +101,12 @@ public function toSql(array $parameters = array(), Connection $dbConnection = nu
         if ($conditionsMode == self::CONDITION_GUESS) {
             $bypass = false;
             if ($this->leftOperand instanceof Parameter) {
-                if (!isset($parameters[$this->leftOperand->getName()])) {
+                if ($this->leftOperand->isDiscardedOnNull() && !isset($parameters[$this->leftOperand->getName()])) {
                     $bypass = true;
                 }
             }
             if ($this->rightOperand instanceof Parameter) {
-                if (!isset($parameters[$this->rightOperand->getName()])) {
+                if ($this->rightOperand->isDiscardedOnNull() && !isset($parameters[$this->rightOperand->getName()])) {
                     $bypass = true;
                 }
             }