Merge pull request #119 from baopham/bao/query-decorator

Add RawDynamoDbQuery class and ability to decorate query

Author: baopham

README.md

@@ -27,7 +27,8 @@ Supports all key types - primary hash key and composite keys.
   * [findOrFail()](#findorfail)
   * [Query scope](#query-scope)
   * [REMOVE — Deleting Attributes From An Item](#remove--deleting-attributes-from-an-item)
-  * [toSql() style](#tosql-style)
+  * [toSql() Style](#tosql-style)
+  * [Decorate Query](#decorate-query)
 * [Indexes](#indexes)
 * [Composite Keys](#composite-keys)
 * [Requirements](#requirements)
@@ -258,17 +259,49 @@ Model::find('foo')->removeAttribute('name', 'description', 'nested.foo', 'nested
 ```
 
 
-#### toSql() style
+#### toSql() Style
 
 For debugging purposes, you can choose to convert to the actual DynamoDb query
 
 ```php
-list($op, $query) = $model->where('count', '>', 10)->toDynamoDbQuery();
+$raw = $model->where('count', '>', 10)->toDynamoDbQuery();
+// $op is either "Scan" or "Query"
+$op = $raw->op;
+// The query body being sent to AWS
+$query = $raw->query;
 ```
 
-where `$op` will be either `Scan` or `Query` and `$query` will be the query body being sent to AWS.
+where `$raw` is an instance of [RawDynamoDbQuery](./src/RawDynamoDbQuery.php)
 
 
+#### Decorate Query
+
+Use `decorate` when you want to enhance the query. For example:
+
+To set the order of the sort key:
+
+```php
+$items = $model
+    ->where('hash', 'hash-value')
+    ->where('range', '>', 10)
+    ->decorate(function (RawDynamoDbQuery $raw) {
+        // desc order
+        $raw->query['ScanIndexForward'] = false;
+    })
+    ->get();
+```
+
+To force to use "Query" instead of "Scan" if the library fails to detect the correct operation:
+
+```php
+$items = $model
+    ->where('hash', 'hash-value')
+    ->decorate(function (RawDynamoDbQuery $raw) {
+        $raw->op = 'Query';
+    })
+    ->get();
+```
+
 Indexes
 -----------
 If your table has indexes, make sure to declare them in your model class like so

src/DynamoDbQueryBuilder.php

@@ -38,6 +38,11 @@ class DynamoDbQueryBuilder
      */
     protected $client;
 
+    /**
+     * @var Closure
+     */
+    protected $decorator;
+
     /**
      * Applied global scopes.
      *
@@ -557,6 +562,12 @@ public function count()
         return $this->getAll($this->model->getKeyNames())->count();
     }
 
+    public function decorate(Closure $closure)
+    {
+        $this->decorator = $closure;
+        return $this;
+    }
+
     protected function getAll(
         $columns = [],
         $limit = DynamoDbQueryBuilder::MAX_LIMIT,
@@ -570,19 +581,23 @@ protected function getAll(
             }
         }
 
-        list($op, $query) = $this->toDynamoDbQuery($columns, $limit);
+        $raw = $this->toDynamoDbQuery($columns, $limit);
+
+        if ($this->decorator) {
+            call_user_func($this->decorator, $raw);
+        }
 
         if ($useIterator) {
-            $iterator = $this->client->getIterator($op, $query);
+            $iterator = $this->client->getIterator($raw->op, $raw->query);
 
-            if (isset($query['Limit'])) {
-                $iterator = new \LimitIterator($iterator, 0, $query['Limit']);
+            if (isset($raw->query['Limit'])) {
+                $iterator = new \LimitIterator($iterator, 0, $raw->query['Limit']);
             }
         } else {
-            if ($op === 'Scan') {
-                $res = $this->client->scan($query);
+            if ($raw->op === 'Scan') {
+                $res = $this->client->scan($raw->query);
             } else {
-                $res = $this->client->query($query);
+                $res = $this->client->query($raw->query);
             }
 
             $this->lastEvaluatedKey = array_get($res, 'LastEvaluatedKey');
@@ -601,13 +616,22 @@ protected function getAll(
         return $this->getModel()->newCollection($results);
     }
 
+    /**
+     * Return the raw DynamoDb query
+     *
+     * @param array $columns
+     * @param int $limit
+     * @return RawDynamoDbQuery
+     */
     public function toDynamoDbQuery(
         $columns = [],
         $limit = DynamoDbQueryBuilder::MAX_LIMIT
     ) {
         $this->applyScopes();
 
-        list($op, $query) = $this->buildExpressionQuery();
+        $raw = $this->buildExpressionQuery();
+
+        $query = $raw->query;
 
         $query['TableName'] = $this->model->getTable();
 
@@ -623,8 +647,8 @@ public function toDynamoDbQuery(
             $query['ExclusiveStartKey'] = $this->lastEvaluatedKey;
         }
 
-        $query = $this->cleanUpQuery($query);
-        return [$op, $query];
+        $raw->query = $this->cleanUpQuery($query);
+        return $raw;
     }
 
     protected function buildExpressionQuery()
@@ -635,7 +659,7 @@ protected function buildExpressionQuery()
         $query = [];
 
         if (empty($this->wheres)) {
-            return [$op, $query];
+            return new RawDynamoDbQuery($op, $query);
         }
 
         // Index key condition exists, then use Query instead of Scan.
@@ -695,7 +719,7 @@ protected function buildExpressionQuery()
 
         $query['ExpressionAttributeValues'] = $this->expressionAttributeValues->all();
 
-        return [$op, $query];
+        return new RawDynamoDbQuery($op, $query);
     }
 
     protected function conditionsAreExactSearch()

src/RawDynamoDbQuery.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace BaoPham\DynamoDb;
+
+/**
+ * Class RawDynamoDbQuery
+ *
+ * @package BaoPham\DynamoDb
+ */
+class RawDynamoDbQuery implements \IteratorAggregate, \ArrayAccess, \Countable
+{
+    /**
+     * Either 'Scan', or 'Query'
+     *
+     * @var string
+     */
+    public $op;
+
+    /**
+     * The query body being sent to AWS
+     *
+     * @var array
+     */
+    public $query;
+
+    /**
+     * For backward compatibility, previously we use array to represent the raw query
+     *
+     * @var array
+     */
+    private $array;
+
+    public function __construct($op, $query)
+    {
+        $this->op = $op;
+        $this->query = $query;
+        $this->array = [$op, $query];
+    }
+
+    /**
+     * Whether a offset exists
+     * @link http://php.net/manual/en/arrayaccess.offsetexists.php
+     * @param mixed $offset <p>
+     * An offset to check for.
+     * </p>
+     * @return boolean true on success or false on failure.
+     * </p>
+     * <p>
+     * The return value will be casted to boolean if non-boolean was returned.
+     * @since 5.0.0
+     */
+    public function offsetExists($offset)
+    {
+        return isset($this->array[$offset]);
+    }
+
+    /**
+     * Offset to retrieve
+     * @link http://php.net/manual/en/arrayaccess.offsetget.php
+     * @param mixed $offset <p>
+     * The offset to retrieve.
+     * </p>
+     * @return mixed Can return all value types.
+     * @since 5.0.0
+     */
+    public function offsetGet($offset)
+    {
+        return $this->array[$offset];
+    }
+
+    /**
+     * Offset to set
+     * @link http://php.net/manual/en/arrayaccess.offsetset.php
+     * @param mixed $offset <p>
+     * The offset to assign the value to.
+     * </p>
+     * @param mixed $value <p>
+     * The value to set.
+     * </p>
+     * @return void
+     * @since 5.0.0
+     */
+    public function offsetSet($offset, $value)
+    {
+        $this->array[$offset] = $value;
+    }
+
+    /**
+     * Offset to unset
+     * @link http://php.net/manual/en/arrayaccess.offsetunset.php
+     * @param mixed $offset <p>
+     * The offset to unset.
+     * </p>
+     * @return void
+     * @since 5.0.0
+     */
+    public function offsetUnset($offset)
+    {
+        unset($this->array[$offset]);
+    }
+
+    /**
+     * Retrieve an external iterator
+     * @link http://php.net/manual/en/iteratoraggregate.getiterator.php
+     * @return Traversable An instance of an object implementing <b>Iterator</b> or
+     * <b>Traversable</b>
+     * @since 5.0.0
+     */
+    public function getIterator()
+    {
+        return new \ArrayObject($this->array);
+    }
+
+    /**
+     * Count elements of an object
+     * @link http://php.net/manual/en/countable.count.php
+     * @return int The custom count as an integer.
+     * </p>
+     * <p>
+     * The return value is cast to an integer.
+     * @since 5.1.0
+     */
+    public function count()
+    {
+        return count($this->array);
+    }
+}

tests/DynamoDbCompositeModelTest.php

@@ -3,6 +3,7 @@
 namespace BaoPham\DynamoDb\Tests;
 
 use BaoPham\DynamoDb\NotSupportedException;
+use BaoPham\DynamoDb\RawDynamoDbQuery;
 use \Illuminate\Database\Eloquent\ModelNotFoundException;
 
 /**
@@ -297,14 +298,14 @@ public function testConditionContainingIndexKey()
 
     public function testSetIndexManually()
     {
-        list($op, $query) = $this->testModel
+        $raw = $this->testModel
             ->where('id', 'id1')
             ->where('author', 'BP')
             ->withIndex('id_author_index')
             ->toDynamoDbQuery();
 
-        $this->assertEquals('id_author_index', array_get($query, 'IndexName'));
-        $this->assertEquals('Query', $op);
+        $this->assertEquals('id_author_index', array_get($raw->query, 'IndexName'));
+        $this->assertEquals('Query', $raw->op);
     }
 
     public function testConditionsNotContainingAllCompositeKeys()
@@ -384,7 +385,7 @@ public function testRemoveAttributesOnModel()
 
     public function testAfterForQueryOperation()
     {
-        for ($i = 0; $i < 10; $i++) {
+        foreach (range(0, 9) as $i) {
             $this->seed(['count' => ['N' => $i]]);
         }
 
@@ -405,6 +406,29 @@ public function testAfterForQueryOperation()
         $this->assertEquals(range(0, 9), $paginationResult->sort()->values()->toArray());
     }
 
+    public function testDecorateRawQuery()
+    {
+        foreach (range(0, 9) as $i) {
+            $this->seed(['id' => ['S' => 'id'], 'count' => ['N' => $i]]);
+        }
+
+        $query = $this->testModel
+            ->where('id', 'id')
+            ->where('count', '>=', 0);
+
+        $forward = $query->get();
+
+        $this->assertEquals(range(0, 9), $forward->pluck('count')->toArray());
+
+        $query->decorate(function (RawDynamoDbQuery $raw) {
+            $raw->query['ScanIndexForward'] = false;
+        });
+
+        $reverse = $query->get();
+
+        $this->assertEquals(range(9, 0, -1), $reverse->pluck('count')->toArray());
+    }
+
     public function seed($attributes = [], $exclude = [])
     {
         $item = [