diff --git a/src/Client.php b/src/Client.php index d65077b..b591019 100644 --- a/src/Client.php +++ b/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 { diff --git a/src/Interfaces/ClientInterface.php b/src/Interfaces/ClientInterface.php index 8fc82bb..169b766 100644 --- a/src/Interfaces/ClientInterface.php +++ b/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; } diff --git a/src/Query.php b/src/Query.php index ffe0d93..c80c071 100644 --- a/src/Query.php +++ b/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 { diff --git a/src/ShortsTrait.php b/src/ShortsTrait.php index 0b55154..0eba55d 100644 --- a/src/ShortsTrait.php +++ b/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(); + } }