Util.php

Show:

inherited

Classes
- \PEAR2\Net\RouterOS\Util

Table of Contents

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

Author: Vasil Rangelov
Category: Net
Copyright: 2011 Vasil Rangelov
License: LGPL License 2.1
Link: http://pear2.php.net/PEAR2_Net_RouterOS
Package: PEAR2_Net_RouterOS
Version: 1.0.0b4

\PEAR2\Net\RouterOS\Util
jump to top

Package: PEAR2_Net_RouterOS

Utility class.

Abstracts away frequently used functionality (particularly CRUD operations) in convinient to use methods by wrapping around a connection.

Author: Vasil Rangelov
Category: Net
License: LGPL License 2.1
Link: http://pear2.php.net/PEAR2_Net_RouterOS

Properties

\PEAR2\Net\RouterOS\Client $client

The connection to wrap around.

Details

Type: \PEAR2\Net\RouterOS\Client

array $idCache = null

An array with the numbers of entries in the current menu as keys, and the corresponding IDs as values.

Default valuenullDetails

Type: array

string $menu = '/'

The current menu.

Default value'/'Details

Type: string

Methods

__construct(\PEAR2\Net\RouterOS\Client $client) : void

Creates a new Util instance.

Wraps around a connection to provide convinience methods.

Parameters

Name	Type	Description
$client	\PEAR2\Net\RouterOS\Client	The connection to wrap around.

_escapeCharacters(string $chars) : string

static

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.

Parameters

Name	Type	Description
$chars	string	The matches array, expected to contain exactly one member, in which is the whole string to be escaped.

Returns

Type	Description
string	The escaped character.

_exec(string $source, array $params = array(), string $policy = null, string $name = null, bool $get = false) : \PEAR2\Net\RouterOS\ResponseCollection | string

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.

Parameters

Name	Type	Description
$source	string	A script to execute.
$params	array	An array of local variables to make available in the script. Variable names are array keys, and variable values are array values. Note that the script's (generated) name is always added as the variable "_", which you can overwrite from here. Native PHP types will be converted to their RouterOS equivalents. DateTime and DateInterval objects will be casted to RouterOS' "time" type. Other types are casted to strings.
$policy	string	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.
$name	string	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.
$get	bool	Whether to keep the script after execution.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection \| string	If the script was not added successfully before execution, the ResponseCollection from the add attempt is going to be returned. Otherwise, the (generated) name of the script.

add(array $values) : string

Adds a new entry at the current menu.

Parameters

Name	Type	Description
$values	array	Accepts one or more entries to add to the current menu. The data about each entry is specified as an array with the names of each property as an array key, and the value as an array value.

Returns

Type	Description
string	A comma separated list of the new entries' IDs.

changeMenu(string $newMenu = '') : string

Changes the current menu.

Parameters

Name	Type	Description
$newMenu	string	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.

Returns

Type	Description
string	The old menu. If an empty string is given for a new menu, no change is performed, and this function returns the current menu.

clearIdCache() : \PEAR2\Net\RouterOS\Util

Clears the ID cache.

Normally, the ID cache improves performance when targeting entries 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 entries, the cache may end up being out of date. By calling this method right before targeting an entry with a number, you can ensure number accuracy. Note that Util's {@link move()} and {@link remove()} methods automatically clear the cache before returning, while {@link add()} adds the new entry'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 find()} with a callback.

Returns

Type	Description
\PEAR2\Net\RouterOS\Util	The Util object itself.

Details

Fluent: This method is part of a fluent interface and will return the same instance

disable() : \PEAR2\Net\RouterOS\ResponseCollection

Disables all entries 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 entries. See {@link find()} for a description of what criteria are accepted.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

doBulk(string $what, array $args = array()) : \PEAR2\Net\RouterOS\ResponseCollection

Performs an action on a bulk of entries at the current menu.

Parameters

Name	Type	Description
$what	string	What action to perform.
$args	array	Zero or more arguments can be specified, each being a criteria. If zero arguments are specified, removes all entries. See {@link find()} for a description of what criteria are accepted.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

edit(mixed $numbers, array $newValues) : \PEAR2\Net\RouterOS\ResponseCollection

Alias of {@link set()}

Parameters

Name	Type	Description
$numbers	mixed	Targeted entries. Can be any criteria accepted by {@link find()}.
$newValues	array	An array with the names of each changed property as an array key, and the new value as an array value.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

enable() : \PEAR2\Net\RouterOS\ResponseCollection

Enables all entries 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 entries. See {@link find()} for a description of what criteria are accepted.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

escapeString(string $value) : string

static

Escapes a string for a RouterOS scripting context.

Escapes a string for a RouterOS scripting context. The value can 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.

Parameters

Name	Type	Description
$value	string	Value to be escaped.

Returns

Type	Description
string	The escaped value.

escapeValue(mixed $value) : string

static

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 are casted to strings.

Parameters

Name	Type	Description
$value	mixed	The value to be escaped.

Returns

Type	Description
string	A string representation that can be directly inserted in a script as a whole value.

exec(string $source, array $params = array(), string $policy = null, string $name = null) : \PEAR2\Net\RouterOS\ResponseCollection

Executes a RouterOS script.

Executes a RouterOS script, written as a string. 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.

Parameters

Name	Type	Description
$source	string	A script to execute.
$params	array	An array of local variables to make available in the script. Variable names are array keys, and variable values are array values. Array values are automatically processed with {@link escapeValue()}. Note that the script's (generated) name is always added as the variable "_", which you can overwrite from here.
$policy	string	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.
$name	string	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.

Returns

Type	Description
\PEAR2\Net\RouterOS\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.

fileGetContents(string $filename, string $tmpScriptName = null) : string | bool

Gets the contents of a specified file.

Parameters

Name	Type	Description
$filename	string	The name of the file to get the contents of.
$tmpScriptName	string	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.

Returns

Type	Description
string \| bool	The contents of the file or FALSE if there is no such file.

filePutContents(string $filename, string $data, bool $overwrite = false) : bool

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). If you want an efficient way of transferring files, use (T)FTP.

Parameters

Name	Type	Description
$filename	string	The filename to write data in.
$data	string	The data the file is going to have.
$overwrite	bool	Whether to overwrite the file if it exists.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

find() : string

Finds the IDs of entries at the current menu.

Finds the IDs of entries 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 entries' 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 entry, with the entry 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.

Returns

Type	Description
string	A comma separated list of all entries matching the specified criteria.

get(int | string | null $number, string $value_name) : string | null | bool

Gets a value of a specified entry at the current menu.

Parameters

Name	Type	Description
$number	int \| string \| null	A number identifying the entry you're targeting. Can also be an ID or (in some menus) name. For menus where there are no entries (e.g. "/system identity"), you can specify NULL.
$value_name	string	The name of the value you want to get.

Returns

Type	Description
string \| null \| bool	The value of the specified property. If the property is not set, NULL will be returned. If no such entry exists, FALSE will be returned.

move(mixed $numbers, mixed $destination) : \PEAR2\Net\RouterOS\ResponseCollection

Moves entries at the current menu before a certain other entry.

Moves entries before a certain other entry. Note that the "move" command is not available on all menus. As a rule of thumb, if the order of entries 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.

Parameters

Name	Type	Description
$numbers	mixed	Targeted entries. Can be any criteria accepted by {@link find()}.
$destination	mixed	Entry before which the targeted entries will be moved to. Can be any criteria accepted by {@link find()}. If multiple entries match the criteria, the targeted entries will move above the first match.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

parseValue(string $value) : mixed

static

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 escapeValue()}. That is, results from that method, if given to this method, should produce equivalent results.

Parameters

Name	Type	Description
$value	string	The value to be parsed. Must be a literal of a value, e.g. what {@link escapeValue()} will give you.

Returns

Type	Description
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.

remove() : \PEAR2\Net\RouterOS\ResponseCollection

Removes all entries 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 entries. See {@link find()} for a description of what criteria are accepted.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

set(mixed $numbers, array $newValues) : \PEAR2\Net\RouterOS\ResponseCollection

Sets new values.

Sets new values on certain properties on all entries at the current menu which match certain criteria.

Parameters

Name	Type	Description
$numbers	mixed	Targeted entries. Can be any criteria accepted by {@link find()} or NULL in case the menu is one without entries (e.g. "/system identity").
$newValues	array	An array with the names of each property to set as an array key, and the new value as an array value.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	returns the response collection, allowing you to inspect errors, if any.

unsetValue(mixed $numbers, string $value_name) : \PEAR2\Net\RouterOS\ResponseCollection

Unsets a value of a specified entry 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.

Parameters

Name	Type	Description
$numbers	mixed	Targeted entries. Can be any criteria accepted by {@link find()}.
$value_name	string	The name of the value you want to unset.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection

Util.php

\PEAR2\Net\RouterOS\Utiljump to top

Properties

Methods

\PEAR2\Net\RouterOS\Util
jump to top