Merge pull request #40 from EvilFreelancer/development

Update to version 1.3

Author: EvilFreelancer

.gitignore

@@ -2,4 +2,4 @@
 /vendor/
 /composer.lock
 /clover.xml
-/.phpunit.result.cache
+/.phpunit.result.cache

.travis.yml

@@ -27,7 +27,7 @@ before_script:
 - ./preconf.tcl 12223 > /dev/null || true
 - ./preconf.tcl 22223 > /dev/null || true
 - composer self-update
-- composer install --prefer-source --no-interaction --dev
+- composer install --no-interaction --dev
 
 script:
 - vendor/bin/phpunit --coverage-clover=coverage.clover

README.md

@@ -6,7 +6,7 @@
 [![Code Coverage](https://scrutinizer-ci.com/g/EvilFreelancer/routeros-api-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/EvilFreelancer/routeros-api-php/?branch=master)
 [![Scrutinizer CQ](https://scrutinizer-ci.com/g/evilfreelancer/routeros-api-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/evilfreelancer/routeros-api-php/)
 
-# RouterOS PHP7 API Client
+# RouterOS API Client
 
     composer require evilfreelancer/routeros-api-php
 
@@ -17,6 +17,11 @@ to work with PHP7 in accordance with the PSR standards.
 You can use this library with pre-6.43 and post-6.43 versions of
 RouterOS firmware, it will be detected automatically on connection stage.
 
+## Minimum requirements
+
+* `php` >= 7.2
+* `ext-sockets`
+
 ## Laravel framework support
 
 RouterOS API client is optimized for usage as normal Laravel package, all functional is available via `\RouterOS` facade,
@@ -32,37 +37,48 @@ $config = new \RouterOS\Config([
 $client = new \RouterOS\Client($config);
 ```
 
-Call facade and pass array of parameters to `getClient` method:
+Call facade and pass array of parameters to `client` method:
 
 ```php
-$client = \RouterOS::getClient([
+$client = \RouterOS::client([
     'host' => '192.168.1.3',
     'user' => 'admin',
     'pass' => 'admin',
     'port' => 8728,
 ]);
 ```
 
-### Laravel installation
+You also may get array with all configs which was obtained from `routeros-api.php` file:
+
+```php
+$config = \RouterOS::config([
+    'host' => '192.168.1.3',
+    'user' => 'admin',
+    'pass' => 'admin',
+    'port' => 8728,
+]);
 
-Install the package via Composer:
+dump($config);
 
-    composer require evilfreelancer/routeros-api-php
+$client = \RouterOS::client($config);
+```
 
-By default the package will automatically register its service provider, but
-if you are a happy owner of Laravel version less than 5.3, then in a project, which is using your package
+### Laravel installation
+
+By default, the package will automatically register its service provider, but
+if you are a happy owner of Laravel version less than 5.5, then in a project, which is using your package
 (after composer require is done, of course), add into`providers` block of your `config/app.php`:
 
 ```php
 'providers' => [
     // ...
-    RouterOS\Laravel\ClientServiceProvider::class,
+    RouterOS\Laravel\ServiceProvider::class,
 ],
 ```
 
 Optionally, publish the configuration file if you want to change any defaults:
 
-    php artisan vendor:publish --provider="RouterOS\\Laravel\\ClientServiceProvider"
+    php artisan vendor:publish --provider="RouterOS\\Laravel\\ServiceProvider"
 
 ## How to use
 
@@ -88,18 +104,53 @@ $query =
 $response = $client->query($query)->read();
 
 var_dump($response);
+```
+
+Basic example for update/create/delete types of queries:
 
-// Send "equal" query
+```php
+use \RouterOS\Client;
+use \RouterOS\Query;
+
+// Initiate client with config object
+$client = new Client([
+    'host' => '192.168.1.3',
+    'user' => 'admin',
+    'pass' => 'admin'
+]);
+
+// Send "equal" query with details about IP address which should be created
 $query =
     (new Query('/ip/hotspot/ip-binding/add'))
         ->equal('mac-address', '00:00:00:00:40:29')
         ->equal('type', 'bypassed')
         ->equal('comment', 'testcomment');
 
-// Send query and read response from RouterOS (ordinary answer to update/create/delete queries has empty body)
+// Send query and read response from RouterOS (ordinary answer from update/create/delete queries has empty body)
 $response = $client->query($query)->read();
+
+var_dump($response);
 ```
 
+If you need export all settings from router:
+
+```php
+use \RouterOS\Client;
+
+// Initiate client with config object
+$client = new Client([
+    'host'     => '192.168.1.3',
+    'user'     => 'admin',
+    'pass'     => 'admin',
+    'ssh_port' => 22222,
+]);
+
+// Execute export command via ssh, because API /export method has a bug
+$response = $client->export();
+
+print_r($response);
+``` 
+
 Examples with "where" conditions, "operations" and "tag":
 
 ```php
@@ -257,10 +308,10 @@ need to create a "Query" object whose first argument is the
 required command, after this you can add the attributes of the
 command to "Query" object.
 
-More about attributes and "words" from which this attributes
+More about attributes and "words" from which these attributes
 should be created [here](https://wiki.mikrotik.com/wiki/Manual:API#Command_word). 
 
-More about "expressions", "where" and other filters/modificators
+More about "expressions", "where", "equal" and other filters/modifications
 of your query you can find [here](https://wiki.mikrotik.com/wiki/Manual:API#Queries).
 
 Simple usage examples of Query class:
@@ -271,6 +322,13 @@ use \RouterOS\Query;
 // Get all installed packages (it may be enabled or disabled)
 $query = new Query('/system/package/getall');
 
+// Send "equal" query with details about IP address which should be created
+$query =
+    (new Query('/ip/hotspot/ip-binding/add'))
+        ->equal('mac-address', '00:00:00:00:40:29')
+        ->equal('type', 'bypassed')
+        ->equal('comment', 'testcomment');
+
 // Set where interface is disabled and ID is ether1 (with tag 4)
 $query = 
     (new Query('/interface/set'))
@@ -285,7 +343,7 @@ $query =
         ->where('type', 'vlan')
         ->operations('|');
 
-/// Get all routes that have non-empty comment
+// Get all routes that have non-empty comment
 $query =
     (new Query('/ip/route/print'))
         ->where('comment', '>', null);
@@ -357,8 +415,8 @@ $query->operations('|');
 
 // Enable interface (tag is 4)
 $query = new Query('/interface/set');
-$query->where('disabled', 'no');
-$query->where('.id', 'ether1');
+$query->equal('disabled', 'no');
+$query->equal('.id', 'ether1');
 $query->tag(4);
 
 // Or
@@ -396,8 +454,8 @@ $response = $client->query($query)->read();
 
 ## Read response as Iterator
 
-By default original solution of this client is not optimized for
-work with large amount of results, only for small count of lines
+By default, original solution of this client is not optimized for
+work with a large amount of results, only for small count of lines
 in response from RouterOS API.
 
 But some routers may have (for example) 30000+ records in
@@ -468,6 +526,75 @@ $client->query($query1)->query($query2)->query($query3);
 $client->q($query1)->q($query2)->q($query3);
 ```
 
+## Known issues
+
+### Unable to establish socket session, Operation timed out
+
+This error means that the library cannot connect to your router,
+it may mean router turned off (then need turn on), or the API service not enabled.
+
+Go to `Mikrotik Router OS -> IP -> Services` and enable `api` service.
+
+Or via command line:
+
+```shell script
+/ip service enable api 
+```
+
+### How to update/remove/create something via API?
+
+Instead of `->where()` method of `Query` class you need to
+use `->equal()` method:
+
+```php
+// Create query which should remove security profile
+$query = new \RouterOS\Query('/interface/wireless/security-profiles/remove');
+
+// It will generate queries, which stared from "?" symbol:
+$query->where('.id', '*1');
+
+/*
+// Sample with ->where() method
+RouterOS\Query Object
+(
+    [_attributes:RouterOS\Query:private] => Array
+        (
+            [0] => ?.id=*1
+        )
+
+    [_operations:RouterOS\Query:private] => 
+    [_tag:RouterOS\Query:private] => 
+    [_endpoint:RouterOS\Query:private] => /interface/wireless/security-profiles/remove
+)
+*/
+
+// So, as you can see, instead of `->where()` need to use `->equal()`
+// It will generate queries, which stared from "=" symbol:
+$query->equal('.id', '*1');
+
+/*
+// Sample with ->equal() method
+RouterOS\Query Object
+(
+    [_attributes:RouterOS\Query:private] => Array
+        (
+            [0] => =.id=*1
+        )
+
+    [_operations:RouterOS\Query:private] => 
+    [_tag:RouterOS\Query:private] => 
+    [_endpoint:RouterOS\Query:private] => /interface/wireless/security-profiles/remove
+)
+*/
+```
+
+### Undefined character (any non-English languages)
+
+RouterOS does not support national languages, only English (and API of RouterOS too).
+
+You can try to reproduce it via web, for example add the comment to any
+element of your system, then save and reload the page, you will see unreadable characters.
+
 ## Testing
 
 You can use my [other project](https://github.com/EvilFreelancer/docker-routeros)

composer.json

@@ -33,22 +33,25 @@
   "extra": {
     "laravel": {
       "providers": [
-        "RouterOS\\Laravel\\ClientServiceProvider"
+        "RouterOS\\Laravel\\ServiceProvider"
       ],
       "aliases": {
-        "RouterOS": "RouterOS\\Laravel\\ClientFacade"
+        "RouterOS": "RouterOS\\Laravel\\Facade"
       }
     }
   },
   "require": {
     "php": "^7.2",
-    "ext-sockets": "*"
+    "ext-sockets": "*",
+    "divineomega/php-ssh-connection": "^2.2"
   },
   "require-dev": {
-    "phpunit/phpunit": "^7.0",
-    "orchestra/testbench": "^3.0",
+    "limedeck/phpunit-detailed-printer": "^5.0",
+    "orchestra/testbench": "^4.0|^5.0",
+    "phpunit/phpunit": "^8.0",
     "roave/security-advisories": "dev-master",
-    "squizlabs/php_codesniffer": "^3.5"
+    "squizlabs/php_codesniffer": "^3.5",
+    "larapack/dd": "^1.1"
   },
   "scripts": {
     "test": "phpunit --coverage-clover clover.xml",

configs/routeros-api.php

@@ -1,13 +1,39 @@
 <?php
 
 return [
-    // 'host'     => null,
-    // 'user'     => null,
-    // 'pass'     => null,
-    // 'port'     => null,
-    'ssl'      => false,
-    'legacy'   => false,
-    'timeout'  => 10,
-    'attempts' => 10,
-    'delay'    => 1,
+
+    /*
+     |--------------------------------------------------------------------------
+     | Connection details
+     |--------------------------------------------------------------------------
+     |
+     | Here you may specify different information about your router, like
+     | hostname (or ip-address), username, password, port and ssl mode.
+     |
+     | SSH port should be set if you want to use "/export" command.
+     |
+     */
+
+    'host'     => '192.168.88.1', // Address of Mikrotik RouterOS
+    'user'     => 'admin',        // Username
+    'pass'     => null,           // Password
+    'port'     => 8728,           // RouterOS API port number for access (if not set use default or default with SSL if SSL enabled)
+    'ssl'      => false,          // Enable ssl support (if port is not set this parameter must change default port to ssl port)
+    'ssh_port' => 22,             // Number of SSH port
+
+    /*
+     |--------------------------------------------------------------------------
+     | Optional connection settings of client
+     |--------------------------------------------------------------------------
+     |
+     | Settings bellow need to advanced tune of your connection, for example
+     | you may enable legacy mode by default, or change timeout of connection.
+     |
+     */
+
+    'legacy'   => false, // Support of legacy login scheme (true - pre 6.43, false - post 6.43)
+    'timeout'  => 10,    // Max timeout for answer from RouterOS
+    'attempts' => 10,    // Count of attempts to establish TCP session
+    'delay'    => 1,     // Delay between attempts in seconds
+
 ];

examples/bridge_hosts.php

@@ -22,5 +22,5 @@
 $query = new Query('/interface/bridge/host/print');
 
 // Send query to RouterOS
-$response = $client->write($query)->read();
+$response = $client->query($query)->read();
 print_r($response);

examples/different_queries.php

@@ -14,12 +14,12 @@
 ]);
 
 for ($i = 0; $i < 10; $i++) {
-    $response = $client->wr('/ip/address/print');
+    $response = $client->qr('/ip/address/print');
     print_r($response);
 
-    $response = $client->wr('/ip/arp/print');
+    $response = $client->qr('/ip/arp/print');
     print_r($response);
 
-    $response = $client->wr('/interface/print');
+    $response = $client->qr('/interface/print');
     print_r($response);
 }