routeros-api-php/README.md

RouterOS PHP7 API Client

composer require evilfreelancer/routeros-api-php

This library is partly based on this old project, but unlike it has many innovations to ease development. In addition, the project is designed 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.

How to use

Basic example

All available examples you can find here.

Get all IP addresses (analogue via command line is /ip address print):

<?php
require_once __DIR__ . '/vendor/autoload.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 query to RouterOS without parameters
$request = $client->write('/ip/address/print'); // or $client->write(['/ip/address/print']);

// Read answer from RouterOS
$response = $client->read();
var_dump($response);

// Send query to RouterOS with parameters
$request = $client->write([
    '/queue/simple/print',
    '?target=192.168.1.1/32'
]);

// Read answer from RouterOS
$response = $client->read();
var_dump($response);

You can simplify your code and send then read from socket in one line:

$response = $client->write($query)->read();
var_dump($response);

// Or
$response = $client->w($query)->r();
var_dump($response);

// Single method analog of lines above is
$response = $client->wr($query);
var_dump($response);

By the way, you can send few queries to your router without result:

$client->write($query1)->write($query2)->write($query3);

// Or
$client->w($query1)->w($query2)->w($query3);

Solving issue Allowed memory size of ... bytes exhausted

Rosario is a wrapper for the Client class was developed specifically to solve the problem of excess memory consumption. It includes the functionality that extends the work with the router's response as an array.

To use it you just need replace Client class to Rosario

<?php
require_once __DIR__ . '/vendor/autoload.php';

use \RouterOS\Rosario;

// Initiate client with config
$client = new Rosario([
    'timeout' => 1,
    'host'    => '127.0.0.1',
    'user'    => 'admin',
    'pass'    => 'admin'
]);

// Send query to RouterOS and read response
$response = $client->write('/ip/firewall/address-list/print')->read();
print_r($response);

How to configure the client

// Enable config class
use \RouterOS\Config;

// Create object of config class in one call
$config = new Config([
    'host' => '192.168.1.3',
    'user' => 'admin',
    'pass' => 'admin'
]);

// Create object of class
$config = new Config();

// Set parameters of config
$config->set('host', '192.168.1.3')
$config->set('user', 'admin')
$config->set('pass', 'admin');

// `set()` method supported inline style of syntax
$config
    ->set('host', '192.168.1.3')
    ->set('user', 'admin')
    ->set('pass', 'admin');

Sample of basic code:

use \RouterOS\Config;
use \RouterOS\Client;

$config = new Config([
    'host' => '192.168.1.3',
    'user' => 'admin',
    'pass' => 'admin'
]);

$client = new Client($config);

Or you can just create preconfigured client object with all required settings like below:

use \RouterOS\Client;

$client = new Client([
    'host' => '192.168.1.3',
    'user' => 'admin',
    'pass' => 'admin'
]);

List of available configuration parameters

Parameter	Type	Default	Description
host	string		(required) Address of Mikrotik RouterOS
user	string		(required) Username
pass	string		(required) Password
port	int		RouterOS API port number for access (if not set use 8728 or 8729 if SSL enabled)
ssl	bool	false	Enable ssl support (if port is not set this parameter must change default port to ssl port)
legacy	bool	false	Support of legacy login scheme (true - pre 6.43, false - post 6.43)
timeout	int	10	Max timeout for answer from RouterOS
attempts	int	10	Count of attempts to establish TCP session
delay	int	1	Delay between attempts in seconds

How to enable support of legacy login schema (RouterOS pre-6.43)

From 0.8.1 this is not important, version of firmware will be detected automatically.

<?php
require_once __DIR__ . '/vendor/autoload.php';

use \RouterOS\Client;

// Initiate client with config object
$client = new Client([
    'host'   => '192.168.1.3',
    'user'   => 'admin',
    'pass'   => 'admin',
    'legacy' => true // you need set `legacy` parameter with `true` value
]);

// Your code below...

How to write queries

You can write absolutely any queries to your router, for this you 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 should be created here.

More about "expressions", "where" and other filters/modificators of your query you can find here.

Simple usage examples of Query class:

use \RouterOS\Query;

// One line query: Get all packages
$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'
]);

Advanced usage examples of Query class:

use \RouterOS\Query;

// One line query: Get all packages
$query = new Query('/system/package/getall');

$query = new Query();
$query->setEndpoint('/system/package/getall');

// Multiline query: Enable interface and add tag
$query = new Query('/interface/set');
$query
    ->add('=disabled=no')
    ->add('=.id=ether1')
    ->add('.tag=4');

// Multiline query (via setter): Get all ethernet and VLAN interfaces
$query = new Query('/interface/print');
$query->setAttributes([
    '?type=ether',
    '?type=vlan',
    '?#|'
]);

// Multiline query: Get all routes that have non-empty comment
$query = new Query('/ip/route/print');
$query
    ->add('?>comment=');

Testing

You can use my other project with RouterOS in Docker container for running unit testing on your computer, for this you just need to have Expect, Docker and Docker Compose.

Next clone the repo with RouterOS in Docker and exec docker-compose up -d, then you need preconfigure virtual routers via preconf.tcl script from root of routeros-api-php:

./preconf.tcl 12223
./preconf.tcl 22223

And after this you can run tests:

./vendor/bin/phpunit

Links

• Cloud Hosted Router - Virtual images of RouterOS for your hypervisor
• RouterOS Manual:API - In case if you are wondering what is insane