Add sorting support, fixes #41 (#43)

* Add sort support, fixes #41

* Docs

Author: Synchro

README.md

@@ -91,6 +91,20 @@ Airtable::where('id', '5')->get();
 Airtable::where('id', '>', '5')->get();
 ```
 
+#### Sorting records
+
+- First argument is the column name
+- Second argument is the sort direction: `asc` (default) or `desc`
+
+``` php
+Airtable::orderBy('id')->get();
+Airtable::orderBy('created_at', 'desc')->get();
+```
+You can sort by multiple fields by calling `orderBy` more than once (a single call with array syntax is not supported):
+```php
+Airtable::orderBy('id')->orderBy('created_at', 'desc')->get();
+```
+
 #### First or Create
 - First argument will be used for finding existing
 - Second argument is additional data to save if no results are found and we are creating (will not be saved used if item already exists)

src/Airtable.php

@@ -106,6 +106,13 @@ public function where($column, $operator, $value = null)
         return $this;
     }
 
+    public function orderBy(string $column, string $direction = 'asc')
+    {
+        $this->api->addSort($column, $direction);
+
+        return $this;
+    }
+
     public function firstOrCreate(array $idData, array $createData = [])
     {
         foreach ($idData as $key => $value) {

src/Api/AirtableApiClient.php

@@ -16,6 +16,7 @@ class AirtableApiClient implements ApiClient
 
     private $filters = [];
     private $fields = [];
+    private $sorts = [];
     private $offset = false;
     private $pageSize = 100;
     private $maxRecords = 100;
@@ -60,6 +61,17 @@ public function addFilter($column, $operation, $value)
         return $this;
     }
 
+    public function addSort(string $column, string $direction = 'asc')
+    {
+        if ($direction === 'desc') {
+            $this->sorts[] = ['field' => $column, 'direction' => $direction];
+        } else {
+            $this->sorts[] = ['field' => $column];
+        }
+
+        return $this;
+    }
+
     public function setTable($table)
     {
         $this->table = $table;
@@ -231,6 +243,10 @@ protected function getQueryParams(): array
             $query_params['offset'] = $this->offset;
         }
 
+        if ($this->sorts) {
+            $query_params['sort'] = $this->sorts;
+        }
+
         return $query_params;
     }
 }

tests/ClientTest.php

@@ -20,8 +20,8 @@ public function it_can_be_instantiated()
     public function it_can_post()
     {
         $expectedResponse = [
-            'id' => 'randomlygenerated',
-            'fields' => ['Company Name' => 'Tapp Network'],
+            'id'          => 'randomlygenerated',
+            'fields'      => ['Company Name' => 'Tapp Network'],
             'createdTime' => 'timestamp',
         ];
 
@@ -32,7 +32,7 @@ public function it_can_post()
             '/v0/test_base/companies',
             [
                 'json' => [
-                    'fields' => (object) $postData,
+                    'fields' => (object)$postData,
                 ],
             ]
         );
@@ -75,6 +75,78 @@ public function it_can_search()
         $this->assertEquals($expectedResponse['fields'], $first['fields']);
     }
 
+    /** @test */
+    public function it_can_sort()
+    {
+        //Ascending sort
+        $expectedResponseAsc = [
+            [
+                'id'          => 0,
+                'fields'      => ['Company Name' => 'A Network'],
+                'createdTime' => 'timestamp',
+            ],
+            [
+                'id'          => 1,
+                'fields'      => ['Company Name' => 'B Network'],
+                'createdTime' => 'timestamp',
+            ],
+        ];
+
+        $mockGuzzle = $this->mock_guzzle_request(
+            json_encode($expectedResponseAsc),
+            '/v0/test_base/companies',
+            [
+                'json' => [
+                    'sort' => '[{field:"Company Name",direction:"asc"}]',
+                ],
+            ]
+        );
+
+        $client = $this->build_client($mockGuzzle);
+
+        $actualResponse = $client->setTable('companies')
+            ->addSort('Company Name', 'asc')
+            ->get();
+
+        $first = $actualResponse['records'][0];
+
+        $this->assertEquals($expectedResponseAsc['fields'], $first['fields']);
+
+        //Descending sort
+        $expectedResponseDesc = [
+            [
+                'id'          => 1,
+                'fields'      => ['Company Name' => 'B Network'],
+                'createdTime' => 'timestamp',
+            ],
+            [
+                'id'          => 0,
+                'fields'      => ['Company Name' => 'A Network'],
+                'createdTime' => 'timestamp',
+            ],
+        ];
+
+        $mockGuzzle = $this->mock_guzzle_request(
+            json_encode($expectedResponseDesc),
+            '/v0/test_base/companies',
+            [
+                'json' => [
+                    'sort' => '[{field:"Company Name",direction:"desc"}]',
+                ],
+            ]
+        );
+
+        $client = $this->build_client($mockGuzzle);
+
+        $actualResponse = $client->setTable('companies')
+            ->addSort('Company Name', 'desc')
+            ->get();
+
+        $first = $actualResponse['records'][0];
+
+        $this->assertEquals($expectedResponseDesc['fields'], $first['fields']);
+    }
+
     private function build_client($mockGuzzle = null)
     {
         if (env('LOG_HTTP')) {