From 239ab7e43c38ca4e6f39de80cc37ed7fbcd2d188 Mon Sep 17 00:00:00 2001 From: Paul Rock Date: Wed, 24 Jul 2019 00:17:22 +0300 Subject: [PATCH] tune of documentation and response classes --- README.md | 49 ++++++++++++++++++++++---------------- src/Client.php | 4 ++-- src/Interfaces/ClientInterface.php | 5 +++- src/Interfaces/QueryInterface.php | 8 +++---- src/ShortsTrait.php | 16 ++++++------- 5 files changed, 46 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 6bdf869..c374280 100644 --- a/README.md +++ b/README.md @@ -47,11 +47,12 @@ $request = $client->write('/ip/address/print'); // or $client->write(['/ip/addre $response = $client->read(); var_dump($response); -// Send query to RouterOS with parameters -$request = $client->write([ - '/queue/simple/print', - '?target=192.168.1.1/32' -]); +// Send advanced query with parameters to RouterOS +$query = + (new Query('/queue/simple/print')) + ->where('target', '192.168.1.1/32'); + +$request = $client->write($query); // Read answer from RouterOS $response = $client->read(); @@ -229,23 +230,15 @@ Simple usage examples of Query class: ```php use \RouterOS\Query; -// One line query: Get all packages +// Get all installed packages (it may be enabled or disabled) $query = new Query('/system/package/getall'); -// Multiline query: Enable interface and add tag -$query = new Query('/interface/set', [ - '=disabled=no', - '=.id=ether1', - '.tag=4' -]); - -// Multiline query in simple array -$query = new Query([ - '/interface/set', - '=disabled=no', - '=.id=ether1', - '.tag=4' -]); +// Set where interface is disabled and ID is ether1 (with tag 4) +$query = + (new Query('/interface/set')) + ->where('disabled', 'no') + ->where('.id', 'ether1') + ->tag(4); ``` Advanced usage examples of Query class: @@ -266,6 +259,22 @@ $query ->add('=.id=ether1') ->add('.tag=4'); + +// Multiline query: Enable interface and add tag +$query = new Query('/interface/set', [ + '=disabled=no', + '=.id=ether1', + '.tag=4' +]); + +// Multiline query: In simple array +$query = new Query([ + '/interface/set', + '=disabled=no', + '=.id=ether1', + '.tag=4' +]); + // Multiline query (via setter): Get all ethernet and VLAN interfaces $query = new Query('/interface/print'); $query->setAttributes([ diff --git a/src/Client.php b/src/Client.php index e03b719..b230a2e 100644 --- a/src/Client.php +++ b/src/Client.php @@ -78,10 +78,10 @@ class Client implements Interfaces\ClientInterface * Send write query to RouterOS (with or without tag) * * @param string|array|\RouterOS\Query $query - * @return \RouterOS\Interfaces\ClientInterface + * @return \RouterOS\Client * @throws \RouterOS\Exceptions\QueryException */ - public function write($query): self + public function write($query): Client { if (\is_string($query)) { $query = new Query($query); diff --git a/src/Interfaces/ClientInterface.php b/src/Interfaces/ClientInterface.php index 1e03c5e..8fc82bb 100644 --- a/src/Interfaces/ClientInterface.php +++ b/src/Interfaces/ClientInterface.php @@ -2,6 +2,8 @@ namespace RouterOS\Interfaces; +use RouterOS\Client; + /** * Interface ClientInterface * @@ -64,6 +66,7 @@ interface ClientInterface * Send write query to RouterOS (with or without tag) * * @param string|array|\RouterOS\Query $query + * @return \RouterOS\Client */ - public function write($query); + public function write($query): Client; } diff --git a/src/Interfaces/QueryInterface.php b/src/Interfaces/QueryInterface.php index e0c5c03..019c875 100644 --- a/src/Interfaces/QueryInterface.php +++ b/src/Interfaces/QueryInterface.php @@ -15,14 +15,14 @@ interface QueryInterface /** * Where logic of query * - * @param string $key Key which need to find - * @param bool $value Value which need to check (by default true) - * @param string|null $operator It may be one from list [-,=,>,<] + * @param string $key Key which need to find + * @param bool|string|int $value Value which need to check (by default true) + * @param bool|string|int $operator It may be one from list [-,=,>,<] * @return \RouterOS\Query * @throws \RouterOS\Exceptions\ClientException * @since 1.0.0 */ - public function where(string $key, $value = true, string $operator = ''); + public function where(string $key, $operator = '=', $value = null); /** * Append additional operations diff --git a/src/ShortsTrait.php b/src/ShortsTrait.php index 8be64f4..0b55154 100644 --- a/src/ShortsTrait.php +++ b/src/ShortsTrait.php @@ -2,8 +2,6 @@ namespace RouterOS; -use RouterOS\Interfaces\ClientInterface; - /** * Trait ShortsTrait * @@ -18,10 +16,10 @@ trait ShortsTrait * Alias for ->write() method * * @param string|array|\RouterOS\Query $query - * @return \RouterOS\Interfaces\ClientInterface + * @return \RouterOS\Client * @throws \RouterOS\Exceptions\QueryException */ - public function w($query): ClientInterface + public function w($query): Client { return $this->write($query); } @@ -41,10 +39,10 @@ trait ShortsTrait /** * Alias for ->readAsIterator() method * - * @return mixed + * @return \RouterOS\ResponseIterator * @since 0.7 */ - public function ri() + public function ri(): ResponseIterator { return $this->readAsIterator(); } @@ -65,15 +63,15 @@ trait ShortsTrait } /** - * Alias for ->write()->read() combination of methods + * Alias for ->write()->readAsIterator() combination of methods * * @param string|array|\RouterOS\Query $query - * @return array + * @return \RouterOS\ResponseIterator * @throws \RouterOS\Exceptions\ClientException * @throws \RouterOS\Exceptions\QueryException * @since 0.6 */ - public function wri($query): array + public function wri($query): ResponseIterator { return $this->write($query)->readAsIterator(); }