Set fetch order during query (Webklex#41)

* Set fetch order during query

* Documents query fetching order

* Add back `$message_key` to `Query::get()`

Fix bug introduced by cb43ff2

Author: Max13

README.md

@@ -1,3 +1,4 @@
+
 # IMAP Library for PHP
 
 [![Latest Version on Packagist][ico-version]][link-packagist]
@@ -503,6 +504,41 @@ $messages = $folder->query()->whereAll()
 ->get();
 ```
 
+Change messages fetch order:
+```php
+/** @var \Webklex\PHPIMAP\Folder $folder */
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereText('Hello world')
+->setFetchOrder('asc')
+->get();
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereAll()
+->setFetchOrderAsc()
+->get();
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereAll()
+->fetchOrderAsc()
+->get();
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereText('Hello world')
+->setFetchOrder('desc')
+->get();
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereAll()
+->setFetchOrderDesc()
+->get();
+
+/** @var \Webklex\PHPIMAP\Support\MessageCollection $messages */
+$messages = $folder->query()->whereAll()
+->fetchOrderDesc()
+->get();
+```
+
 
 #### Events
 The following events are available:
@@ -774,6 +810,9 @@ if you're just wishing a feature ;)
 | setFetchOptions    | boolean $fetch_options            | WhereQuery        | Set the fetch options |
 | setFetchBody       | boolean $fetch_body               | WhereQuery        | Set the fetch body option |
 | setFetchFlags      | boolean $fetch_flags              | WhereQuery        | Set the fetch flags option |
+| setFetchOrder      | string $fetch_order               | WhereQuery        | Change the fetch ordering (`asc` is "oldest first", `desc` is "newest first") |
+| setFetchOrderAsc   |                                   | WhereQuery        | Change the fetch ordering to ascending |
+| setFetchOrderDesc  |                                   | WhereQuery        | Change the fetch ordering to descending |
 | leaveUnread        |                                   | WhereQuery        | Don't mark all messages as "read" while fetching:  |
 | markAsRead         |                                   | WhereQuery        | Mark all messages as "read" while fetching |  
 | paginate           | int $perPage = 5, $page = null, $pageName = 'imap_page' | LengthAwarePaginator | Paginate the current query. |

src/Query/Query.php

@@ -62,6 +62,9 @@ class Query {
     /** @var int $fetch_flags */
     protected $fetch_flags = true;
 
+    /** @var int $fetch_order */
+    protected $fetch_order;
+
     /** @var string $date_format */
     protected $date_format;
 
@@ -75,6 +78,12 @@ public function __construct(Client $client, $charset = 'UTF-8') {
 
         if(ClientManager::get('options.fetch') === IMAP::FT_PEEK) $this->leaveUnread();
 
+        if (ClientManager::get('options.fetch_order') === 'desc') {
+            $this->fetch_order = 'desc';
+        } else {
+            $this->fetch_order = 'asc';
+        }
+
         $this->date_format = ClientManager::get('date_format', 'd M y');
 
         $this->charset = $charset;
@@ -193,17 +202,16 @@ public function get() {
 
                 $messages->total($available_messages_count);
 
-                $options = ClientManager::get('options');
-
-                if(strtolower($options['fetch_order']) === 'desc'){
+                if ($this->fetch_order === 'desc') {
                     $available_messages = $available_messages->reverse();
                 }
 
+                $message_key = ClientManager::get('options.message_key');
                 $query =& $this;
 
-                $available_messages->forPage($this->page, $this->limit)->each(function($msgno, $msglist) use(&$messages, $options, $query) {
+                $available_messages->forPage($this->page, $this->limit)->each(function($msgno, $msglist) use(&$messages, $message_key, $query) {
                     $message = $query->getMessage($msgno, $msglist);
-                    switch ($options['message_key']){
+                    switch ($message_key){
                         case 'number':
                             $message_key = $message->getMessageNo();
                             break;
@@ -468,4 +476,61 @@ public function setFetchFlags($fetch_flags) {
         $this->fetch_flags = $fetch_flags;
         return $this;
     }
-}
+
+    /**
+     * @param string $fetch_order
+     * @return Query
+     */
+    public function setFetchOrder($fetch_order) {
+        $fetch_order = strtolower($fetch_order);
+
+        if (in_array($fetch_order, ['asc', 'desc'])) {
+            $this->fetch_order = $fetch_order;
+        }
+
+        return $this;
+    }
+
+    /**
+     * @param string $fetch_order
+     * @return Query
+     */
+    public function fetchOrder($fetch_order) {
+        return $this->setFetchOrder($fetch_order);
+    }
+
+    /**
+     * @return string
+     */
+    public function getFetchOrder() {
+        return $this->fetch_order;
+    }
+
+    /**
+     * @return Query
+     */
+    public function setFetchOrderAsc() {
+        return $this->setFetchOrder('asc');
+    }
+
+    /**
+     * @return Query
+     */
+    public function fetchOrderAsc($fetch_order) {
+        return $this->setFetchOrderAsc();
+    }
+
+    /**
+     * @return Query
+     */
+    public function setFetchOrderDesc() {
+        return $this->setFetchOrder('desc');
+    }
+
+    /**
+     * @return Query
+     */
+    public function fetchOrderDesc($fetch_order) {
+        return $this->setFetchOrderDesc();
+    }
+}