Add 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,19 +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
 $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,
@@ -572,6 +583,10 @@ protected function getAll(
 
         $raw = $this->toDynamoDbQuery($columns, $limit);
 
+        if ($this->decorator) {
+            call_user_func($this->decorator, $raw);
+        }
+
         if ($useIterator) {
             $iterator = $this->client->getIterator($raw->op, $raw->query);
 

src/RawDynamoDbQuery.php

@@ -10,11 +10,15 @@
 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;

tests/DynamoDbCompositeModelTest.php

@@ -3,6 +3,7 @@
 namespace BaoPham\DynamoDb\Tests;
 
 use BaoPham\DynamoDb\NotSupportedException;
+use BaoPham\DynamoDb\RawDynamoDbQuery;
 use \Illuminate\Database\Eloquent\ModelNotFoundException;
 
 /**
@@ -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 = [

tests/DynamoDbModelTest.php

@@ -3,6 +3,7 @@
 namespace BaoPham\DynamoDb\Tests;
 
 use BaoPham\DynamoDb\NotSupportedException;
+use BaoPham\DynamoDb\RawDynamoDbQuery;
 use \Illuminate\Database\Eloquent\ModelNotFoundException;
 
 /**
@@ -721,7 +722,7 @@ public function testAfterForQueryOperation()
 
     public function testAfterForScanOperation()
     {
-        for ($i = 0; $i < 10; $i++) {
+        foreach (range(0, 9) as $i) {
             $this->seed(['count' => ['N' => $i]]);
         }
 
@@ -741,6 +742,28 @@ public function testAfterForScanOperation()
         $this->assertEquals(range(0, 9), $paginationResult->sort()->values()->toArray());
     }
 
+    public function testDecorateRawQuery()
+    {
+        foreach (range(0, 9) as $i) {
+            $this->seed(['count' => ['N' => $i]]);
+        }
+
+        $items = $this->testModel
+            ->decorate(function (RawDynamoDbQuery $raw) {
+                $raw->op = 'Scan';
+                $raw->query['FilterExpression'] = '#count > :count';
+                $raw->query['ExpressionAttributeNames'] = [
+                    '#count' => 'count'
+                ];
+                $raw->query['ExpressionAttributeValues'] = [
+                    ':count' => ['N' => 0],
+                ];
+            })
+            ->get();
+
+        $this->assertEquals(range(1, 9), $items->pluck('count')->sort()->values()->toArray());
+    }
+
     protected function assertRemoveAttributes($item)
     {
         $this->assertNull($item->name);