advanced query implemented to Client class

src/Client.php

@@ -74,7 +74,7 @@ class Client implements Interfaces\ClientInterface
     }
 
     /**
-     * Send write query to RouterOS (with or without tag)
+     * Send write query to RouterOS
      *
      * @param string|array|\RouterOS\Query $query
      * @return \RouterOS\Client
@@ -93,6 +93,64 @@ class Client implements Interfaces\ClientInterface
             throw new QueryException('Parameters cannot be processed');
         }
 
+        // Submit query to RouterOS
+        return $this->writeRAW($query);
+    }
+
+    /**
+     * Send write query to RouterOS (modern version of write)
+     *
+     * @param string      $endpoint   Path of API query
+     * @param array|null  $where      List of where filters
+     * @param string|null $operations Some operations which need make on response
+     * @param string|null $tag        Mark query with tag
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    public function query(string $endpoint, array $where = null, string $operations = null, string $tag = null): Client
+    {
+        // If endpoint is string then build Query object
+        $query = new Query($endpoint);
+
+        // Parse where array
+        if (!empty($where)) {
+
+            // If array is multidimensional, then parse each line
+            if (is_array($where[0])) {
+                foreach ($where as [$key, $operator, $value]) {
+                    $query->where($key, $operator, $value);
+                }
+            } else {
+                $query->where($where[0], $where[1] ?? null, $where[2] ?? null);
+            }
+
+        }
+
+        // Append operations if set
+        if (!empty($operations)) {
+            $query->operations($operations);
+        }
+
+        // Append tag if set
+        if (!empty($tag)) {
+            $query->tag($tag);
+        }
+
+        // Submit query to RouterOS
+        return $this->writeRAW($query);
+    }
+
+    /**
+     * Send write query object to RouterOS
+     *
+     * @param \RouterOS\Query $query
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    private function writeRAW(Query $query): Client
+    {
         // Send commands via loop to router
         foreach ($query->getQuery() as $command) {
             $this->_connector->writeWord(trim($command));
@@ -105,18 +163,12 @@ class Client implements Interfaces\ClientInterface
     }
 
     /**
-     * Read answer from server after query was executed
+     * Read RAW response from RouterOS
      *
-     * A Mikrotik reply is formed of blocks
-     * Each block starts with a word, one of ('!re', '!trap', '!done', '!fatal')
-     * Each block end with an zero byte (empty line)
-     * Reply ends with a complete !done or !fatal block (ended with 'empty line')
-     * A !fatal block precedes TCP connexion close
-     *
-     * @param bool $parse
-     * @return mixed
+     * @return array
+     * @since 1.0.0
      */
-    public function read(bool $parse = true)
+    private function readRAW(): array
     {
         // By default response is empty
         $response = [];
@@ -150,6 +202,27 @@ class Client implements Interfaces\ClientInterface
         }
 
         // Parse results and return
+        return $response;
+    }
+
+    /**
+     * Read answer from server after query was executed
+     *
+     * A Mikrotik reply is formed of blocks
+     * Each block starts with a word, one of ('!re', '!trap', '!done', '!fatal')
+     * Each block end with an zero byte (empty line)
+     * Reply ends with a complete !done or !fatal block (ended with 'empty line')
+     * A !fatal block precedes TCP connexion close
+     *
+     * @param bool $parse
+     * @return mixed
+     */
+    public function read(bool $parse = true)
+    {
+        // Read RAW response
+        $response = $this->readRAW();
+
+        // Parse results and return
         return $parse ? $this->rosario($response) : $response;
     }
 
@@ -157,6 +230,7 @@ class Client implements Interfaces\ClientInterface
      * Read using Iterators to improve performance on large dataset
      *
      * @return \RouterOS\ResponseIterator
+     * @since 1.0.0
      */
     public function readAsIterator(): ResponseIterator
     {

src/Interfaces/ClientInterface.php

@@ -63,10 +63,23 @@ interface ClientInterface
     public function read(bool $parse);
 
     /**
-     * Send write query to RouterOS (with or without tag)
+     * Send write query to RouterOS
      *
      * @param string|array|\RouterOS\Query $query
      * @return \RouterOS\Client
      */
     public function write($query): Client;
+
+    /**
+     * Send write query to RouterOS (modern version of write)
+     *
+     * @param string      $endpoint   Path of API query
+     * @param array|null  $where      List of where filters
+     * @param string|null $operations Some operations which need make on response
+     * @param string|null $tag        Mark query with tag
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    public function query(string $endpoint, array $where, string $operations, string $tag): Client;
 }

src/Query.php

@@ -57,7 +57,7 @@ class Query implements QueryInterface
      *
      * @param array|string $endpoint   Path of endpoint
      * @param array        $attributes List of attributes which should be set
-     * @throws QueryException
+     * @throws \RouterOS\Exceptions\QueryException
      */
     public function __construct($endpoint, array $attributes = [])
     {
@@ -138,7 +138,7 @@ class Query implements QueryInterface
      * Append to array yet another attribute of query
      *
      * @param string $word
-     * @return  \RouterOS\Query
+     * @return \RouterOS\Query
      */
     public function add(string $word): Query
     {
@@ -149,7 +149,7 @@ class Query implements QueryInterface
     /**
      * Get attributes array of current query
      *
-     * @return  array
+     * @return array
      */
     public function getAttributes(): array
     {
@@ -160,8 +160,8 @@ class Query implements QueryInterface
      * Set array of attributes
      *
      * @param array $attributes
-     * @return  \RouterOS\Query
-     * @since   0.7
+     * @return \RouterOS\Query
+     * @since 0.7
      */
     public function setAttributes(array $attributes): Query
     {
@@ -172,7 +172,7 @@ class Query implements QueryInterface
     /**
      * Get endpoint of current query
      *
-     * @return  string|null
+     * @return string|null
      */
     public function getEndpoint()
     {
@@ -183,8 +183,8 @@ class Query implements QueryInterface
      * Set endpoint of query
      *
      * @param string|null $endpoint
-     * @return  \RouterOS\Query
-     * @since   0.7
+     * @return \RouterOS\Query
+     * @since 0.7
      */
     public function setEndpoint(string $endpoint = null): Query
     {
@@ -195,8 +195,8 @@ class Query implements QueryInterface
     /**
      * Build body of query
      *
-     * @return  array
-     * @throws  \RouterOS\Exceptions\QueryException
+     * @return array
+     * @throws \RouterOS\Exceptions\QueryException
      */
     public function getQuery(): array
     {

src/ShortsTrait.php

@@ -25,6 +25,22 @@ trait ShortsTrait
     }
 
     /**
+     * Alias for ->query() method
+     *
+     * @param string      $endpoint   Path of API query
+     * @param array|null  $where      List of where filters
+     * @param string|null $operations Some operations which need make on response
+     * @param string|null $tag        Mark query with tag
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    public function q(string $endpoint, array $where = null, string $operations = null, string $tag = null): Client
+    {
+        return $this->query($endpoint, $where, $operations, $tag);
+    }
+
+    /**
      * Alias for ->read() method
      *
      * @param bool $parse
@@ -40,7 +56,7 @@ trait ShortsTrait
      * Alias for ->readAsIterator() method
      *
      * @return \RouterOS\ResponseIterator
-     * @since 0.7
+     * @since 1.0.0
      */
     public function ri(): ResponseIterator
     {
@@ -63,16 +79,49 @@ trait ShortsTrait
     }
 
     /**
+     * Alias for ->write()->read() combination of methods
+     *
+     * @param string      $endpoint   Path of API query
+     * @param array|null  $where      List of where filters
+     * @param string|null $operations Some operations which need make on response
+     * @param string|null $tag        Mark query with tag
+     * @param bool        $parse
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    public function qr(string $endpoint, array $where = null, string $operations = null, string $tag = null, bool $parse = true): array
+    {
+        return $this->query($endpoint, $where, $operations, $tag)->read($parse);
+    }
+
+    /**
      * Alias for ->write()->readAsIterator() combination of methods
      *
      * @param string|array|\RouterOS\Query $query
      * @return \RouterOS\ResponseIterator
      * @throws \RouterOS\Exceptions\ClientException
      * @throws \RouterOS\Exceptions\QueryException
-     * @since 0.6
+     * @since 1.0.0
      */
     public function wri($query): ResponseIterator
     {
         return $this->write($query)->readAsIterator();
     }
+
+    /**
+     * Alias for ->write()->read() combination of methods
+     *
+     * @param string      $endpoint   Path of API query
+     * @param array|null  $where      List of where filters
+     * @param string|null $operations Some operations which need make on response
+     * @param string|null $tag        Mark query with tag
+     * @return \RouterOS\Client
+     * @throws \RouterOS\Exceptions\QueryException
+     * @since 1.0.0
+     */
+    public function qri(string $endpoint, array $where = null, string $operations = null, string $tag = null): array
+    {
+        return $this->query($endpoint, $where, $operations, $tag)->readAsIterator();
+    }
 }