|
| | __construct (Client $client) |
| | Creates a new Util instance. More...
|
| |
| | getMenu () |
| | Gets the current menu. More...
|
| |
| | setMenu ($newMenu) |
| | Sets the current menu. More...
|
| |
| | exec ($source, array $params=array(), $policy=null, $name=null) |
| | Executes a RouterOS script. More...
|
| |
| | clearIdCache () |
| | Clears the ID cache. More...
|
| |
| | find () |
| | Finds the IDs of items at the current menu. More...
|
| |
| | get ($number, $valueName) |
| | Gets a value of a specified item at the current menu. More...
|
| |
| | enable () |
| | Enables all items at the current menu matching certain criteria. More...
|
| |
| | disable () |
| | Disables all items at the current menu matching certain criteria. More...
|
| |
| | remove () |
| | Removes all items at the current menu matching certain criteria. More...
|
| |
| | set ($numbers, array $newValues) |
| | Sets new values. More...
|
| |
| | edit ($numbers, array $newValues) |
| | Alias of static::set(). More...
|
| |
| | unsetValue ($numbers, $valueName) |
| | Unsets a value of a specified item at the current menu. More...
|
| |
| | add (array $values) |
| | Adds a new item at the current menu. More...
|
| |
| | move ($numbers, $destination) |
| | Moves items at the current menu before a certain other item. More...
|
| |
| | count ($mode=COUNT_NORMAL, Query $query=null) |
| | Counts items at the current menu. More...
|
| |
| | getAll (array $args=array(), Query $query=null) |
| | Gets all items in the current menu. More...
|
| |
| | filePutContents ($filename, $data, $overwrite=false) |
| | Puts a file on RouterOS's file system. More...
|
| |
| | fileGetContents ($filename, $tmpScriptName=null) |
| | Gets the contents of a specified file. More...
|
| |
Definition at line 55 of file Util.php.
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. Client or 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 static::move() and static::remove() methods automatically clear the cache before returning, while 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 static::find() with a callback.
- Returns
- $this The Util object itself.
Definition at line 526 of file Util.php.
| count |
( |
|
$mode = COUNT_NORMAL, |
|
|
Query |
$query = null |
|
) |
| |
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 static::find(), where numbers and callbacks are allowed also.
- Parameters
-
| int | $mode | The counter mode. Currently ignored, but present for compatiblity with PHP 5.6+. |
| Query | $query | A query to filter items by. Without it, all items are included in the count. |
- Returns
- 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).
Definition at line 899 of file Util.php.
| static escapeValue |
( |
|
$value | ) |
|
|
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 (i.e. resources and other objects) are casted to strings.
- Parameters
-
| mixed | $value | The value to be escaped. |
- Returns
- string A string representation that can be directly inserted in a script as a whole value.
Definition at line 303 of file Util.php.
| exec |
( |
|
$source, |
|
|
array |
$params = array(), |
|
|
|
$policy = null, |
|
|
|
$name = null |
|
) |
| |
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.
- Parameters
-
| 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. |
| 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 static::escapeValue(). Streams are also supported, and are processed in chunks, each processed with 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. |
| 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. |
| 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. |
- Returns
- 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.
Definition at line 498 of file Util.php.
| filePutContents |
( |
|
$filename, |
|
|
|
$data, |
|
|
|
$overwrite = false |
|
) |
| |
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 static::setMenu() to move to the "/file" menu, and call static::remove() without performing verification afterwards.
- Parameters
-
| string | $filename | The filename to write data in. |
| 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. |
| bool | $overwrite | Whether to overwrite the file if it exists. |
- Returns
- bool TRUE on success, FALSE on failure.
Definition at line 981 of file Util.php.
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 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.
- Returns
- string A comma separated list of all items matching the specified criteria.
Definition at line 552 of file Util.php.
| move |
( |
|
$numbers, |
|
|
|
$destination |
|
) |
| |
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.
- Parameters
-
| mixed | $numbers | Targeted items. Can be any criteria accepted by static::find(). |
| mixed | $destination | item before which the targeted items will be moved to. Can be any criteria accepted by static::find(). If multiple items match the criteria, the targeted items will move above the first match. |
- Returns
- ResponseCollection Returns the response collection, allowing you to inspect errors, if any.
Definition at line 870 of file Util.php.
| static parseValue |
( |
|
$value | ) |
|
|
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 static::escapeValue(). hat is, results from that method, if given to this method, should produce equivalent results.
- Parameters
-
| string | $value | The value to be parsed. Must be a literal of a value, e.g. what static::escapeValue() will give you. |
- Returns
- mixed Depending on RouterOS type detected:
- "nil" or "nothing" - NULL.
- "number" - int or double for large values.
- "bool" - a boolean.
- "time" - a DateInterval object.
- "array" - an array, with the values processed recursively.
- "str" - a string.
- Unrecognized type - treated as an unquoted string.
Definition at line 97 of file Util.php.
| static prepareScript |
( |
|
$source, |
|
|
array |
$params = array() |
|
) |
| |
|
static |
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 static::exec(), but instead you want to store it for later execution, perhaps by supplying it to "/system scheduler".
- Parameters
-
| 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. |
| 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 static::escapeValue(). Streams are also supported, and are processed in chunks, each with 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. |
- Returns
- resource A new PHP temporary stream with the script as contents, with the pointer back at the start.
- See also
- static::appendScript()
Definition at line 218 of file Util.php.
Inheritance diagram for Util:
1.8.8 
