<?php
/**
* RouterOS API client implementation.
*
* RouterOS is the flag product of the company MikroTik and is a powerful router software. One of its many abilities is to allow control over it via an API. This package provides a client for that API, in turn allowing you to use PHP to control RouterOS hosts.
*
* PHP version 5
*
* @category Net
* @package PEAR2_Net_RouterOS
* @author Vasil Rangelov <boen.robot@gmail.com>
* @copyright 2011 Vasil Rangelov
* @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
* @version 1.0.0b5
* @link http://pear2.php.net/PEAR2_Net_RouterOS
*/
/**
* The namespace declaration.
*/
namespace PEAR2\Net\RouterOS;
/**
* Values at {@link Util::exec()} can be casted from this type.
*/
use DateTime;
/**
* Values at {@link Util::exec()} can be casted from this type.
*/
use DateInterval;
/**
* Implemented by this class.
*/
use Countable;
/**
* Used to reliably write to streams at {@link static::prepareScript()}.
*/
use PEAR2\Net\Transmitter\Stream;
/**
* Utility class.
*
* Abstracts away frequently used functionality (particularly CRUD operations)
* in convinient to use methods by wrapping around a connection.
*
* @category Net
* @package PEAR2_Net_RouterOS
* @author Vasil Rangelov <boen.robot@gmail.com>
* @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
* @link http://pear2.php.net/PEAR2_Net_RouterOS
*/
class Util implements Countable
{
/**
* @var Client The connection to wrap around.
*/
protected $client;
/**
* @var string The current menu.
*/
protected $menu = '/';
/**
* @var array|null An array with the numbers of items in the current menu as
* keys, and the corresponding IDs as values. NULL when the cache needs
* regenerating.
*/
protected $idCache = null;
/**
* Parses a value from a RouterOS scripting context.
*
* Turns a value from RouterOS into an equivalent PHP value, based on
* determining the type in the same way RouterOS would determine it for a
* literal.
*
* This method is intended to be the very opposite of
* {@link static::escapeValue()}. hat is, results from that method, if
* given to this method, should produce equivalent results.
*
* @param string $value The value to be parsed. Must be a literal of a
* value, e.g. what {@link static::escapeValue()} will give you.
*
* @return mixed Depending on RouterOS type detected:
* - "nil" or "nothing" - NULL.
* - "number" - int or double for large values.
* - "bool" - a boolean.
* - "time" - a {@link DateInterval} object.
* - "array" - an array, with the values processed recursively.
* - "str" - a string.
* - Unrecognized type - treated as an unquoted string.
*/
public static function parseValue($value)
{
$value = (string)$value;
if (in_array($value, array('', 'nil'), true)) {
return null;
} elseif (in_array($value, array('true', 'false', 'yes', 'no'), true)) {
return $value === 'true' || $value === 'yes';
} elseif ($value === (string)($num = (int)$value)
|| $value === (string)($num = (double)$value)
) {
return $num;
} elseif (preg_match(
'/^
(?:(\d+)w)?
(?:(\d+)d)?
(?:(\d\d)\:)?
(\d\d)\:
(\d\d(:\.\d{1,6})?)
$/x',
$value,
$time
)) {
$days = isset($time[2]) ? (int)$time[2] : 0;
if (isset($time[1])) {
$days += 7 * (int)$time[1];
}
if ('' === $time[3]) {
$time[3] = 0;
}
return new DateInterval(
"P{$days}DT{$time[3]}H{$time[4]}M{$time[5]}S"
);
} elseif (('"' === $value[0]) && substr(strrev($value), 0, 1) === '"') {
return str_replace(
array('\"', '\\\\', "\\\n", "\\\r\n", "\\\r"),
array('"', '\\'),
substr($value, 1, -1)
);
} elseif ('{' === $value[0]) {
$len = strlen($value);
if ($value[$len - 1] === '}') {
$value = substr($value, 1, -1);
if ('' === $value) {
return array();
}
$parsedValue = preg_split(
'/
(\"(?:\\\\\\\\|\\\\"|[^"])*\")
|
(\{[^{}]*(?2)?\})
|
([^;=]+)
/sx',
$value,
null,
PREG_SPLIT_DELIM_CAPTURE
);
$result = array();
$newVal = null;
$newKey = null;
for ($i = 0, $l = count($parsedValue); $i < $l; ++$i) {
switch ($parsedValue[$i]) {
case '':
break;
case ';':
if (null === $newKey) {
$result[] = $newVal;
} else {
$result[$newKey] = $newVal;
}
$newKey = $newVal = null;
break;
case '=':
$newKey = static::parseValue($parsedValue[$i - 1]);
$newVal = static::parseValue($parsedValue[++$i]);
break;
default:
$newVal = static::parseValue($parsedValue[$i]);
}
}
if (null === $newKey) {
$result[] = $newVal;
} else {
$result[$newKey] = $newVal;
}
return $result;
}
}
return $value;
}
/**
* Prepares a script.
*
* Prepares a script for eventual execution by prepending parameters as
* variables to it.
*
* This is particularly useful when you're creating scripts that you don't
* want to execute right now (as with {@link static::exec()}, but instead
* you want to store it for later execution, perhaps by supplying it to
* "/system scheduler".
*
* @param string|resource $source The source of the script, as a string
* or stream. If a stream is provided, reading starts from the current
* position to the end of the stream, and the pointer stays at the end
* after reading is done.
* @param array $params An array of parameters to make available
* in the script as local variables.
* Variable names are array keys, and variable values are array values.
* Array values are automatically processed with
* {@link static::escapeValue()}. Streams are also supported, and are
* processed in chunks, each with
* {@link static::escapeString()}. Processing starts from the current
* position to the end of the stream, and the stream's pointer stays at
* the end after reading is done.
*
* @return resource A new PHP temporary stream with the script as contents,
* with the pointer back at the start.
* @see static::appendScript()
*/
public static function prepareScript(
$source,
array $params = array()
) {
$resultStream = fopen('php://temp', 'r+b');
self::appendScript($resultStream, $source, $params);
rewind($resultStream);
return $resultStream;
}
/**
* Appends a script.
*
* Appends a script to an existing stream.
*
* @param resource $stream An existing stream to write the resulting
* script to.
* @param string|resource $source The source of the script, as a string
* or stream. If a stream is provided, reading starts from the current
* position to the end of the stream, and the pointer stays at the end
* after reading is done.
* @param array $params An array of parameters to make available
* in the script as local variables.
* Variable names are array keys, and variable values are array values.
* Array values are automatically processed with
* {@link static::escapeValue()}. Streams are also supported, and are
* processed in chunks, each with
* {@link static::escapeString()}. Processing starts from the current
* position to the end of the stream, and the stream's pointer stays at
* the end after reading is done.
*
* @return int The number of bytes written to $stream is returned,
* and the pointer remains where it was after the write
* (i.e. it is not seeked back, even if seeking is supported).
*/
public static function appendScript(
$stream,
$source,
array $params = array()
) {
$writer = new Stream($stream, false);
$bytes = 0;
foreach ($params as $pname => $pvalue) {
$pname = static::escapeString($pname);
$bytes += $writer->send(":local \"{$pname}\" ");
if (Stream::isStream($pvalue)) {
$reader = new Stream($pvalue, false);
$chunkSize = $reader->getChunk(Stream::DIRECTION_RECEIVE);
$bytes += $writer->send('"');
while ($reader->isAvailable() && $reader->isDataAwaiting()) {
$bytes += $writer->send(
static::escapeString(fread($pvalue, $chunkSize))
);
}
$bytes += $writer->send("\";\n");
} else {
$bytes += $writer->send(static::escapeValue($pvalue) . ";\n");
}
}
$bytes += $writer->send($source);
return $bytes;
}
/**
* Escapes a value for a RouterOS scripting context.
*
* Turns any native PHP value into an equivalent whole value that can be
* inserted as part of a RouterOS script.
*
* DateTime and DateInterval objects will be casted to RouterOS' "time"
* type. A DateTime object will be converted to a time relative to the UNIX
* epoch time. Note that if a DateInterval does not have the "days" property
* ("a" in formatting), then its months and years will be ignored, because
* they can't be unambigiously converted to a "time" value.
*
* Unrecognized types (i.e. resources and other objects) are casted to
* strings.
*
* @param mixed $value The value to be escaped.
*
* @return string A string representation that can be directly inserted in a
* script as a whole value.
*/
public static function escapeValue($value)
{
switch(gettype($value)) {
case 'NULL':
$value = '';
break;
case 'integer':
$value = (string)$value;
break;
case 'boolean':
$value = $value ? 'true' : 'false';
break;
case 'array':
if (0 === count($value)) {
$value = '({})';
break;
}
$result = '';
foreach ($value as $key => $val) {
$result .= ';';
if (!is_int($key)) {
$result .= static::escapeValue($key) . '=';
}
$result .= static::escapeValue($val);
}
$value = '{' . substr($result, 1) . '}';
break;
case 'object':
if ($value instanceof DateTime) {
$usec = $value->format('u');
if ('000000' === $usec) {
unset($usec);
}
$unixEpoch = new DateTime('@0');
$value = $unixEpoch->diff($value);
}
if ($value instanceof DateInterval) {
if (false === $value->days || $value->days < 0) {
$value = $value->format('%r%dd%H:%I:%S');
} else {
$value = $value->format('%r%ad%H:%I:%S');
}
if (strpos('.', $value) === false && isset($usec)) {
$value .= '.' . $usec;
}
break;
}
//break; intentionally omitted
default:
$value = '"' . static::escapeString((string)$value) . '"';
break;
}
return $value;
}
/**
* Escapes a string for a RouterOS scripting context.
*
* Escapes a string for a RouterOS scripting context. The value can then be
* surrounded with quotes at a RouterOS script (or concatenated onto a
* larger string first), and you can be sure there won't be any code
* injections coming from it.
*
* @param string $value Value to be escaped.
*
* @return string The escaped value.
*/
public static function escapeString($value)
{
return preg_replace_callback(
'/[^\\_A-Za-z0-9]+/S',
array(__CLASS__, '_escapeCharacters'),
$value
);
}
/**
* Escapes a character for a RouterOS scripting context.
*
* Escapes a character for a RouterOS scripting context. Intended to only be
* called for non-alphanumeric characters.
*
* @param string $chars The matches array, expected to contain exactly one
* member, in which is the whole string to be escaped.
*
* @return string The escaped characters.
*/
private static function _escapeCharacters($chars)
{
$result = '';
for ($i = 0, $l = strlen($chars[0]); $i < $l; ++$i) {
$result .= '\\' . str_pad(
strtoupper(dechex(ord($chars[0][$i]))),
2,
'0',
STR_PAD_LEFT
);
}
return $result;
}
/**
* Creates a new Util instance.
*
* Wraps around a connection to provide convinience methods.
*
* @param Client $client The connection to wrap around.
*/
public function __construct(Client $client)
{
$this->client = $client;
}
/**
* Gets the current menu.
*
* @return string The current menu.
*/
public function getMenu()
{
return $this->menu;
}
/**
* Sets the current menu.
*
* Sets the current menu.
*
* @param string $newMenu The menu to change to. Can be specified with API
* or CLI syntax and can be either absolute or relative. If relative,
* it's relative to the current menu, which by default is the root.
*
* @return $this The object itself. If an empty string is given for
* a new menu, no change is performed,
* but the ID cache is cleared anyway.
*
* @see static::clearIdCache()
*/
public function setMenu($newMenu)
{
$newMenu = (string)$newMenu;
if ('' !== $newMenu) {
$menuRequest = new Request('/menu');
if ('/' === $newMenu[0]) {
$this->menu = $menuRequest->setCommand($newMenu)->getCommand();
} else {
$this->menu = $menuRequest->setCommand(
'/' . str_replace('/', ' ', substr($this->menu, 1)) . ' ' .
str_replace('/', ' ', $newMenu)
)->getCommand();
}
}
$this->clearIdCache();
return $this;
}
/**
* Executes a RouterOS script.
*
* Executes a RouterOS script, written as a string or a stream.
* Note that in cases of errors, the line numbers will be off, because the
* script is executed at the current menu as context, with the specified
* variables pre declared. This is achieved by prepending 1+count($params)
* lines before your actual script.
*
* @param string|resource $source The source of the script, as a string or
* stream. If a stream is provided, reading starts from the current
* position to the end of the stream, and the pointer stays at the end
* after reading is done.
* @param array $params An array of parameters to make available
* in the script as local variables.
* Variable names are array keys, and variable values are array values.
* Array values are automatically processed with
* {@link static::escapeValue()}. Streams are also supported, and are
* processed in chunks, each processed with
* {@link static::escapeString()}. Processing starts from the current
* position to the end of the stream, and the stream's pointer is left
* untouched after the reading is done.
* Note that the script's (generated) name is always added as the
* variable "_", which will be inadvertently lost if you overwrite it
* from here.
* @param string $policy Allows you to specify a policy the script
* must follow. Has the same format as in terminal.
* If left NULL, the script has no restrictions beyond those imposed by
* the username.
* @param string $name The script is executed after being saved
* in "/system script" under a random name (prefixed with the computer's
* name), and is removed after execution. To eliminate any possibility
* of name clashes, you can specify your own name.
*
* @return ResponseCollection Returns the response collection of the
* run, allowing you to inspect errors, if any.
* If the script was not added successfully before execution, the
* ResponseCollection from the add attempt is going to be returned.
*/
public function exec(
$source,
array $params = array(),
$policy = null,
$name = null
) {
return $this->_exec($source, $params, $policy, $name);
}
/**
* Clears the ID cache.
*
* Normally, the ID cache improves performance when targeting items by a
* number. If you're using both Util's methods and other means (e.g.
* {@link Client} or {@link Util::exec()}) to add/move/remove items, the
* cache may end up being out of date. By calling this method right before
* targeting an item with a number, you can ensure number accuracy.
*
* Note that Util's {@link static::move()} and {@link static::remove()}
* methods automatically clear the cache before returning, while
* {@link static::add()} adds the new item's ID to the cache as the next
* number. A change in the menu also clears the cache.
*
* Note also that the cache is being rebuilt unconditionally every time you
* use {@link static::find()} with a callback.
*
* @return $this The Util object itself.
*/
public function clearIdCache()
{
$this->idCache = null;
return $this;
}
/**
* Finds the IDs of items at the current menu.
*
* Finds the IDs of items based on specified criteria, and returns them as
* a comma separated string, ready for insertion at a "numbers" argument.
*
* Accepts zero or more criteria as arguments. If zero arguments are
* specified, returns all items' IDs. The value of each criteria can be a
* number (just as in Winbox), a literal ID to be included, a {@link Query}
* object, or a callback. If a callback is specified, it is called for each
* item, with the item as an argument. If it returns a true value, the
* item's ID is included in the result. Every other value is casted to a
* string. A string is treated as a comma separated values of IDs, numbers
* or callback names. Non-existent callback names are instead placed in the
* result, which may be useful in menus that accept identifiers other than
* IDs, but note that it can cause errors on other menus.
*
* @return string A comma separated list of all items matching the
* specified criteria.
*/
public function find()
{
if (func_num_args() === 0) {
if (null === $this->idCache) {
$idCache = str_replace(
';',
',',
$this->client->sendSync(
new Request($this->menu . '/find')
)->getProperty('ret')
);
$this->idCache = explode(',', $idCache);
return $idCache;
}
return implode(',', $this->idCache);
}
$idList = '';
foreach (func_get_args() as $criteria) {
if ($criteria instanceof Query) {
foreach ($this->client->sendSync(
new Request($this->menu . '/print .proplist=.id', $criteria)
) as $response) {
$idList .= $response->getProperty('.id') . ',';
}
} elseif (is_callable($criteria)) {
$idCache = array();
foreach ($this->client->sendSync(
new Request($this->menu . '/print')
) as $response) {
if ($criteria($response)) {
$idList .= $response->getProperty('.id') . ',';
}
$idCache[] = $response->getProperty('.id');
}
$this->idCache = $idCache;
} else {
$this->find();
if (is_int($criteria)) {
if (isset($this->idCache[$criteria])) {
$idList = $this->idCache[$criteria] . ',';
}
} else {
$criteria = (string)$criteria;
if ($criteria === (string)(int)$criteria) {
if (isset($this->idCache[(int)$criteria])) {
$idList .= $this->idCache[(int)$criteria] . ',';
}
} elseif (false === strpos($criteria, ',')) {
$idList .= $criteria . ',';
} else {
$criteriaArr = explode(',', $criteria);
for ($i = count($criteriaArr) - 1; $i >= 0; --$i) {
if ('' === $criteriaArr[$i]) {
unset($criteriaArr[$i]);
} elseif ('*' === $criteriaArr[$i][0]) {
$idList .= $criteriaArr[$i] . ',';
unset($criteriaArr[$i]);
}
}
if (!empty($criteriaArr)) {
$idList .= call_user_func_array(
array($this, 'find'),
$criteriaArr
) . ',';
}
}
}
}
}
return rtrim($idList, ',');
}
/**
* Gets a value of a specified item at the current menu.
*
* @param int|string|null $number A number identifying the item you're
* targeting. Can also be an ID or (in some menus) name. For menus where
* there are no items (e.g. "/system identity"), you can specify NULL.
* @param string $valueName The name of the value you want to get.
*
* @return string|null|bool The value of the specified property. If the
* property is not set, NULL will be returned. FALSE on failure
* (e.g. no such item, invalid property, etc.).
*/
public function get($number, $valueName)
{
if (is_int($number) || ((string)$number === (string)(int)$number)) {
$this->find();
if (isset($this->idCache[(int)$number])) {
$number = $this->idCache[(int)$number];
} else {
return false;
}
}
//For new RouterOS versions
$request = new Request($this->menu . '/get');
$request->setArgument('number', $number);
$request->setArgument('value-name', $valueName);
$responses = $this->client->sendSync($request);
if (Response::TYPE_ERROR === $responses->getType()) {
return false;
}
$result = $responses->getProperty('ret');
if (null !== $result) {
return $result;
}
// The "get" of old RouterOS versions returns an empty !done response.
// New versions return such only when the property is not set.
// This is a backup for old versions' sake.
$query = null;
if (null !== $number) {
$number = (string)$number;
$query = Query::where('.id', $number)->orWhere('name', $number);
}
$responses = $this->getAll(
array('.proplist' => $valueName, 'detail'),
$query
);
if (0 === count($responses)) {
// @codeCoverageIgnoreStart
// New versions of RouterOS can't possibly reach this section.
return false;
// @codeCoverageIgnoreEnd
}
return $responses->getProperty($valueName);
}
/**
* Enables all items at the current menu matching certain criteria.
*
* Zero or more arguments can be specified, each being a criteria.
* If zero arguments are specified, enables all items.
* See {@link static::find()} for a description of what criteria are
* accepted.
*
* @return ResponseCollection returns the response collection, allowing you
* to inspect errors, if any.
*/
public function enable()
{
return $this->doBulk('enable', func_get_args());
}
/**
* Disables all items at the current menu matching certain criteria.
*
* Zero or more arguments can be specified, each being a criteria.
* If zero arguments are specified, disables all items.
* See {@link static::find()} for a description of what criteria are
* accepted.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function disable()
{
return $this->doBulk('disable', func_get_args());
}
/**
* Removes all items at the current menu matching certain criteria.
*
* Zero or more arguments can be specified, each being a criteria.
* If zero arguments are specified, removes all items.
* See {@link static::find()} for a description of what criteria are
* accepted.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function remove()
{
$result = $this->doBulk('remove', func_get_args());
$this->clearIdCache();
return $result;
}
/**
* Sets new values.
*
* Sets new values on certain properties on all items at the current menu
* which match certain criteria.
*
* @param mixed $numbers Targeted items. Can be any criteria accepted by
* {@link static::find()} or NULL in case the menu is one without items
* (e.g. "/system identity").
* @param array $newValues An array with the names of each property to set
* as an array key, and the new value as an array value.
* Flags (properties with a value "true" that is interpreted as
* equivalent of "yes" from CLI) can also be specified with a numeric
* index as the array key, and the name of the flag as the array value.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function set($numbers, array $newValues)
{
$setRequest = new Request($this->menu . '/set');
foreach ($newValues as $name => $value) {
if (is_int($name)) {
$setRequest->setArgument($value, 'true');
} else {
$setRequest->setArgument($name, $value);
}
}
if (null !== $numbers) {
$setRequest->setArgument('numbers', $this->find($numbers));
}
return $this->client->sendSync($setRequest);
}
/**
* Alias of {@link static::set()}
*
* @param mixed $numbers Targeted items. Can be any criteria accepted by
* {@link static::find()}.
* @param array $newValues An array with the names of each changed property
* as an array key, and the new value as an array value.
* Flags (properties with a value "true" that is interpreted as
* equivalent of "yes" from CLI) can also be specified with a numeric
* index as the array key, and the name of the flag as the array value.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function edit($numbers, array $newValues)
{
return $this->set($numbers, $newValues);
}
/**
* Unsets a value of a specified item at the current menu.
*
* Equivalent of scripting's "unset" command. The "Value" part in the method
* name is added because "unset" is a language construct, and thus a
* reserved word.
*
* @param mixed $numbers Targeted items. Can be any criteria accepted
* by {@link static::find()}.
* @param string $valueName The name of the value you want to unset.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function unsetValue($numbers, $valueName)
{
$unsetRequest = new Request($this->menu . '/unset');
return $this->client->sendSync(
$unsetRequest->setArgument('numbers', $this->find($numbers))
->setArgument('value-name', $valueName)
);
}
/**
* Adds a new item at the current menu.
*
* @param array $values Accepts one or more items to add to the
* current menu. The data about each item is specified as an array with
* the names of each property as an array key, and the value as an array
* value.
* Flags (properties with a value "true" that is interpreted as
* equivalent of "yes" from CLI) can also be specified with a numeric
* index as the array key, and the name of the flag as the array value.
* @param array $... Additional items.
*
* @return string A comma separated list of the new items' IDs. If a
* particular item was not added, this will be indicated by an empty
* string in its spot on the list. e.g. "*1D,,*1E" means that
* you supplied three items to be added, of which the second one was
* not added for some reason.
*/
public function add(array $values)
{
$addRequest = new Request($this->menu . '/add');
$idList = '';
foreach (func_get_args() as $values) {
$idList .= ',';
if (!is_array($values)) {
continue;
}
foreach ($values as $name => $value) {
if (is_int($name)) {
$addRequest->setArgument($value, 'true');
} else {
$addRequest->setArgument($name, $value);
}
}
$id = $this->client->sendSync($addRequest)->getProperty('ret');
if (null !== $this->idCache) {
$this->idCache[] = $id;
}
$idList .= $id;
$addRequest->removeAllArguments();
}
return substr($idList, 1);
}
/**
* Moves items at the current menu before a certain other item.
*
* Moves items before a certain other item. Note that the "move"
* command is not available on all menus. As a rule of thumb, if the order
* of items in a menu is irrelevant to their interpretation, there won't
* be a move command on that menu. If in doubt, check from a terminal.
*
* @param mixed $numbers Targeted items. Can be any criteria accepted
* by {@link static::find()}.
* @param mixed $destination item before which the targeted items will be
* moved to. Can be any criteria accepted by {@link static::find()}.
* If multiple items match the criteria, the targeted items will move
* above the first match.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
public function move($numbers, $destination)
{
$moveRequest = new Request($this->menu . '/move');
$moveRequest->setArgument('numbers', $this->find($numbers));
$destination = $this->find($destination);
if (false !== strpos($destination, ',')) {
$destination = strstr($destination, ',', true);
}
$moveRequest->setArgument('destination', $destination);
$this->clearIdCache();
return $this->client->sendSync($moveRequest);
}
/**
* Counts items at the current menu.
*
* Counts items at the current menu. This executes a dedicated command
* ("print" with a "count-only" argument) on RouterOS, which is why only
* queries are allowed as a criteria, in contrast with
* {@link static::find()}, where numbers and callbacks are allowed also.
*
* @param int $mode The counter mode.
* Currently ignored, but present for compatiblity with PHP 5.6+.
* @param Query $query A query to filter items by. Without it, all items
* are included in the count.
*
* @return int The number of items, or -1 on failure (e.g. if the
* current menu does not have a "print" command or items to be counted).
*/
public function count($mode = COUNT_NORMAL, Query $query = null)
{
$result = $this->client->sendSync(
new Request($this->menu . '/print count-only=""', $query)
)->end()->getProperty('ret');
if (null === $result) {
return -1;
}
if (Stream::isStream($result)) {
$result = stream_get_contents($result);
}
return (int)$result;
}
/**
* Gets all items in the current menu.
*
* Gets all items in the current menu, using a print request.
*
* @param array<int|string,string> $args Additional arguments to pass
* to the request.
* Each array key is the name of the argument, and each array value is
* the value of the argument to be passed.
* Arguments without a value (i.e. empty arguments) can also be
* specified using a numeric key, and the name of the argument as the
* array value.
* @param Query|null $query A query to filter items by.
* NULL to get all items.
*
* @return ResponseCollection|false A response collection with all
* {@link Response::TYPE_DATA} responses. The collection will be empty
* when there are no matching items. FALSE on failure.
*/
public function getAll(array $args = array(), Query $query = null)
{
$printRequest = new Request($this->menu . '/print', $query);
foreach ($args as $name => $value) {
if (is_int($name)) {
$printRequest->setArgument($value);
} else {
$printRequest->setArgument($name, $value);
}
}
$responses = $this->client->sendSync($printRequest);
if (count($responses->getAllOfType(Response::TYPE_ERROR)) > 0) {
return false;
}
return $responses->getAllOfType(Response::TYPE_DATA);
}
/**
* Puts a file on RouterOS's file system.
*
* Puts a file on RouterOS's file system, regardless of the current menu.
* Note that this is a **VERY VERY VERY** time consuming method - it takes a
* minimum of a little over 4 seconds, most of which are in sleep. It waits
* 2 seconds after a file is first created (required to actually start
* writing to the file), and another 2 seconds after its contents is written
* (performed in order to verify success afterwards).
* Similarly for removal (when $data is NULL) - there are two seconds in
* sleep, used to verify the file was really deleted.
*
* If you want an efficient way of transferring files, use (T)FTP.
* If you want an efficient way of removing files, use
* {@link static::setMenu()} to move to the "/file" menu, and call
* {@link static::remove()} without performing verification afterwards.
*
* @param string $filename The filename to write data in.
* @param string|resource|null $data The data the file is going to have
* as a string or a seekable stream.
* Setting the value to NULL removes a file of this name.
* If a seekable stream is provided, it is sent from its current
* posistion to its end, and the pointer is seeked back to its current
* position after sending.
* Non seekable streams, as well as all other types, are casted to a
* string.
* @param bool $overwrite Whether to overwrite the file if
* it exists.
*
* @return bool TRUE on success, FALSE on failure.
*/
public function filePutContents($filename, $data, $overwrite = false)
{
$printRequest = new Request(
'/file/print .proplist=""',
Query::where('name', $filename)
);
$fileExists = count($this->client->sendSync($printRequest)) > 1;
if (null === $data) {
if (!$fileExists) {
return false;
}
$removeRequest = new Request('/file/remove');
$this->client->sendSync(
$removeRequest->setArgument('numbers', $filename)
);
//Required for RouterOS to REALLY remove the file.
sleep(2);
return !(count($this->client->sendSync($printRequest)) > 1);
}
if (!$overwrite && $fileExists) {
return false;
}
$result = $this->client->sendSync(
$printRequest->setArgument('file', $filename)
);
if (count($result->getAllOfType(Response::TYPE_ERROR)) > 0) {
return false;
}
//Required for RouterOS to write the initial file.
sleep(2);
$setRequest = new Request('/file/set contents=""');
$setRequest->setArgument('numbers', $filename);
$this->client->sendSync($setRequest);
$this->client->sendSync($setRequest->setArgument('contents', $data));
//Required for RouterOS to write the file's new contents.
sleep(2);
$fileSize = $this->client->sendSync(
$printRequest->setArgument('file', null)
->setArgument('.proplist', 'size')
)->getProperty('size');
if (Stream::isStream($fileSize)) {
$fileSize = stream_get_contents($fileSize);
}
if (Communicator::isSeekableStream($data)) {
return Communicator::seekableStreamLength($data) == $fileSize;
} else {
return sprintf('%u', strlen((string)$data)) === $fileSize;
};
}
/**
* Gets the contents of a specified file.
*
* @param string $filename The name of the file to get the contents of.
* @param string $tmpScriptName In order to get the file's contents, a
* script is created at "/system script" with a random name, the
* source of which is then overwriten with the file's contents, and
* finally retrieved. To eliminate any possibility of name clashes, you
* can specify your own name for the script.
*
* @return string|resource|false The contents of the file as a string or as
* new PHP temp stream if the underliying
* {@link Client::isStreamingResponses()} is set to TRUE.
* FALSE is returned if there is no such file.
*/
public function fileGetContents($filename, $tmpScriptName = null)
{
$checkRequest = new Request(
'/file/print',
Query::where('name', $filename)
);
if (1 === count($this->client->sendSync($checkRequest))) {
return false;
}
$contents = $this->_exec(
'/system script set $"_" source=[/file get $filename contents]',
array('filename' => $filename),
null,
$tmpScriptName,
true
);
return $contents;
}
/**
* Performs an action on a bulk of items at the current menu.
*
* @param string $what What action to perform.
* @param array $args Zero or more arguments can be specified, each being
* a criteria. If zero arguments are specified, removes all items.
* See {@link static::find()} for a description of what criteria are
* accepted.
*
* @return ResponseCollection Returns the response collection, allowing you
* to inspect errors, if any.
*/
protected function doBulk($what, array $args = array())
{
$bulkRequest = new Request($this->menu . '/' . $what);
$bulkRequest->setArgument(
'numbers',
call_user_func_array(array($this, 'find'), $args)
);
return $this->client->sendSync($bulkRequest);
}
/**
* Executes a RouterOS script.
*
* Same as the public equivalent, with the addition of allowing you to get
* the contents of the script post execution, instead of removing it.
*
* @param string|resource $source The source of the script, as a string or
* stream. If a stream is provided, reading starts from the current
* position to the end of the stream, and the pointer stays at the end
* after reading is done.
* @param array $params An array of parameters to make available
* in the script as local variables.
* Variable names are array keys, and variable values are array values.
* Array values are automatically processed with
* {@link static::escapeValue()}. Streams are also supported, and are
* processed in chunks, each processed with
* {@link static::escapeString()}. Processing starts from the current
* position to the end of the stream, and the stream's pointer is left
* untouched after the reading is done.
* Note that the script's (generated) name is always added as the
* variable "_", which will be inadvertently lost if you overwrite it
* from here.
* @param string $policy Allows you to specify a policy the script
* must follow. Has the same format as in terminal.
* If left NULL, the script has no restrictions beyond those imposed by
* the username.
* @param string $name The script is executed after being saved
* in "/system script" under a random name (prefixed with the computer's
* name), and is removed after execution. To eliminate any possibility
* of name clashes, you can specify your own name.
* @param bool $get Whether to get the source of the script.
*
* @return ResponseCollection|string Returns the response collection of the
* run, allowing you to inspect errors, if any.
* If the script was not added successfully before execution, the
* ResponseCollection from the add attempt is going to be returned.
* If $get is TRUE, returns the source of the script on success.
*/
private function _exec(
$source,
array $params = array(),
$policy = null,
$name = null,
$get = false
) {
$request = new Request('/system/script/add');
if (null === $name) {
$name = uniqid(gethostname(), true);
}
$request->setArgument('name', $name);
$request->setArgument('policy', $policy);
$params += array('_' => $name);
$finalSource = fopen('php://temp', 'r+b');
fwrite(
$finalSource,
'/' . str_replace('/', ' ', substr($this->menu, 1)). "\n"
);
static::appendScript($finalSource, $source, $params);
fwrite($finalSource, "\n");
rewind($finalSource);
$request->setArgument('source', $finalSource);
$result = $this->client->sendSync($request);
if (0 === count($result->getAllOfType(Response::TYPE_ERROR))) {
$request = new Request('/system/script/run');
$request->setArgument('number', $name);
$result = $this->client->sendSync($request);
if ($get) {
$result = $this->client->sendSync(
new Request(
'/system/script/print .proplist="source"',
Query::where('name', $name)
)
)->getProperty('source');
}
$request = new Request('/system/script/remove');
$request->setArgument('numbers', $name);
$this->client->sendSync($request);
}
return $result;
}
}