Where search accepts now almost everything

Author: Webklex

CHANGELOG.md

@@ -19,11 +19,13 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 - Custom UID alternative support added
 - Fetch additional extensions using `Folder::query(["FEATURE_NAME"])`
 - Optionally move a message during "deletion" instead of just "flagging" it #106 (thanks @EthraZa)
+- `WhereQuery::where()` accepts now a wide range of criteria / values.
 
 ### Affected Classes
 - [Header::class](src/Header.php)
 - [Protocol::class](src/Connection/Protocols/Protocol.php)
 - [Query::class](src/Query/Query.php)
+- [WhereQuery::class](src/Query/WhereQuery.php)
 
 ### Breaking changes
 - All protocol methods which had a `boolean` `$uid` option no longer support a boolean. Use `IMAP::ST_UID` or `IMAP::NIL` instead. If you want to use an alternative to `UID` just use the string instead.

src/Query/WhereQuery.php

@@ -117,34 +117,55 @@ protected function validate_criteria($criteria) {
     }
 
     /**
+     * Register search parameters
      * @param mixed $criteria
      * @param null $value
      *
      * @return $this
      * @throws InvalidWhereQueryCriteriaException
+     *
+     * Examples:
+     * $query->from("[email protected]")->seen();
+     * $query->whereFrom("[email protected]")->whereSeen();
+     * $query->where([["FROM" => "[email protected]"], ["SEEN"]]);
+     * $query->where(["FROM" => "[email protected]"])->where(["SEEN"]);
+     * $query->where(["FROM" => "[email protected]", "SEEN"]);
+     * $query->where("FROM", "[email protected]")->where("SEEN");
      */
     public function where($criteria, $value = null) {
         if (is_array($criteria)) {
             foreach ($criteria as $key => $value) {
                 if (is_numeric($key)) {
-                    return $this->where($value);
+                    $this->where($value);
+                }else{
+                    $this->where($key, $value);
                 }
-                return $this->where($key, $value);
             }
         } else {
-            $criteria = $this->validate_criteria($criteria);
-            $value = $this->parse_value($value);
-
-            if ($value === null || $value === '') {
-                $this->query->push([$criteria]);
-            } else {
-                $this->query->push([$criteria, $value]);
-            }
+            $this->push_search_criteria($criteria, $value);
         }
 
         return $this;
     }
 
+    /**
+     * Push a given search criteria and value pair to the search query
+     * @param $criteria string
+     * @param $value mixed
+     *
+     * @throws InvalidWhereQueryCriteriaException
+     */
+    protected function push_search_criteria($criteria, $value){
+        $criteria = $this->validate_criteria($criteria);
+        $value = $this->parse_value($value);
+
+        if ($value === null || $value === '') {
+            $this->query->push([$criteria]);
+        } else {
+            $this->query->push([$criteria, $value]);
+        }
+    }
+
     /**
      * @param Closure $closure
      *
@@ -468,8 +489,7 @@ public function whereLanguage($country_code) {
      * @return WhereQuery
      * @throws InvalidWhereQueryCriteriaException
      */
-    public function whereUid($uid)
-    {
+    public function whereUid($uid) {
         return $this->where('UID', $uid);
     }
 
@@ -481,8 +501,7 @@ public function whereUid($uid)
      * @return WhereQuery
      * @throws InvalidWhereQueryCriteriaException
      */
-    public function whereUidIn($uids)
-    {
+    public function whereUidIn($uids) {
         $uids = implode(',', $uids);
         return $this->where('UID', $uids);
     }
@@ -491,10 +510,9 @@ public function whereUidIn($uids)
      * Apply the callback if the given "value" is truthy.
      * copied from @url https://github.com/laravel/framework/blob/8.x/src/Illuminate/Support/Traits/Conditionable.php
      *
-     * @param mixed  $value
-     * @param callable  $callback
-     * @param callable|null  $default
-
+     * @param mixed $value
+     * @param callable $callback
+     * @param callable|null $default
      * @return $this|mixed
      */
     public function when($value, $callback, $default = null) {
@@ -511,14 +529,13 @@ public function when($value, $callback, $default = null) {
      * Apply the callback if the given "value" is falsy.
      * copied from @url https://github.com/laravel/framework/blob/8.x/src/Illuminate/Support/Traits/Conditionable.php
      *
-     * @param mixed  $value
-     * @param callable  $callback
-     * @param callable|null  $default
-
+     * @param mixed $value
+     * @param callable $callback
+     * @param callable|null $default
      * @return $this|mixed
      */
     public function unless($value, $callback, $default = null) {
-        if (! $value) {
+        if (!$value) {
             return $callback($this, $value) ?: $this;
         } elseif ($default) {
             return $default($this, $value) ?: $this;