Inheritance diagram for Util:

Collaboration diagram for Util:

Public Member Functions
	__construct (Client $client)
	Creates a new Util instance. More...

	getMenu ()
	Gets the current menu. More...

	setMenu ($newMenu)
	Sets the current menu. More...

	newRequest ( $command, array $args=array(), Query $query=null, $tag=null)
	Creates a Request object. More...

	exec ( $source, array $params=array(), $policy=null, $name=null)
	Executes a RouterOS script. More...

	clearIdCache ()
	Clears the ID cache. More...

	getCurrentTime ()
	Gets the current time on the router. More...

	find ()
	Finds the IDs of items at the current menu. More...

	get ($number, $valueName=null)
	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...

	comment ($numbers, $comment)
	Comments items. More...

	set ($numbers, array $newValues)
	Sets new values. More...

	edit ($numbers, $valueName, $newValue)
	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=null)
	Moves items at the current menu before a certain other item. More...

	count (Query $query=null, $from=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...

Protected Member Functions
	doBulk ($command, array $args=array())
	Performs an action on a bulk of items at the current menu. More...

Protected Attributes
	$client

	$menu = ''

	$idCache = null

Detailed Description

Definition at line 61 of file Util.php.

Constructor & Destructor Documentation

◆ __construct()

__construct ( Client $client )

Creates a new Util instance.

Wraps around a connection to provide convenience methods.

Parameters

Client $client The connection to wrap around.

Definition at line 99 of file Util.php.

Member Function Documentation

◆ add()

add ( array $values )

Adds a new item at the current menu.

Parameters

array<string,string\|resource>\|array<int,string>	$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.
array<string,string\|resource>\|array<int,string>	$... Additional items.

Returns: string A comma separated list of the new items' IDs.

Exceptions

RouterErrorException When one or more items were not succesfully added. Note that the response collection will include all replies of all add commands, including the successful ones, in order.

Definition at line 841 of file Util.php.

◆ clearIdCache()

clearIdCache ( )

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 350 of file Util.php.

◆ comment()

comment	(	$numbers,
		$comment
	)

Comments items.

Sets new comments on all items at the current menu which match certain criteria, using the "comment" command.

Note that not all menus have a "comment" command. Most notably, those are menus without items in them (e.g. "/system identity"), and menus with fixed items (e.g. "/ip service").

Parameters

mixed	$numbers	Targeted items. Can be any criteria accepted by static::find().
string \| resource	$comment	The new comment to set on the item as a string or a seekable stream. If a seekable stream is provided, it is sent from its current position 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.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 699 of file Util.php.

◆ count()

count	(	Query	$query = `null`,
			$from = `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

Query \| null	$query	A query to filter items by. Without it, all items are included in the count.
string \| resource \| null	$from	A comma separated list of item IDs. Any items in the set that still exist at the time of couting are included in the final tally. Note that the $query filters this set further (i.e. the item must be in the list AND match the $query). Leaving the value to NULL means all matching items at the current menu 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 949 of file Util.php.

◆ disable()

disable ( )

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 static::find() for a description of what criteria are accepted.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 630 of file Util.php.

◆ doBulk()

doBulk	(		$command,
		array	$args = `array()`
	)

protected

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

Parameters

string	$command	What command to perform.
array	$args	Zero or more arguments can be specified, each being a criteria. If zero arguments are specified, matches all items. See static::find() for a description of what criteria are accepted.

Returns: ResponseCollection Returns the response collection, allowing you to inspect errors, if any.

Definition at line 1193 of file Util.php.

◆ edit()

edit	(	$numbers,
		$valueName,
		$newValue
	)

Alias of static::set().

Parameters

mixed	$numbers	Items to be modified. Can be any criteria accepted by static::find() or NULL in case the menu is one without items (e.g. "/system identity").
string	$valueName	Name of property to be modified.
string \| resource \| null	$newValue	The new value to set. If set to NULL, the property is unset.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 780 of file Util.php.

◆ enable()

enable ( )

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 static::find() for a description of what criteria are accepted.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 602 of file Util.php.

◆ exec()

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<string\|int,mixed>	$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() with all bytes being escaped. 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. Variables with a value of type "nothing" can be declared with a numeric array key and the variable name as the array value (that is casted to a string). 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 \| null	$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 \| null	$name	The script is executed after being saved in "/system script" and is removed after execution. If this argument is left NULL, a random string, prefixed with the computer's name, is generated and used as the script's name. To eliminate any possibility of name clashes, you can specify your own name instead.

Returns: ResponseCollection The responses of all requests involved, i.e. the add, the run and the remove.

Exceptions

RouterErrorException When there is an error in any step of the way. The reponses include all successful commands prior to the error as well. If the error occurs during the run, there will also be a remove attempt, and the results will include its results as well.

Definition at line 259 of file Util.php.

◆ fileGetContents()

fileGetContents	(	$filename,
		$tmpScriptName = `null`
	)

Gets the contents of a specified file.

Parameters

string	$filename	The name of the file to get the contents of.
string \| null	$tmpScriptName	In order to get the file's contents, a script is created at "/system script", the source of which is then overwritten with the file's contents, then retrieved from there, after which the script is removed. If this argument is left NULL, a random string, prefixed with the computer's name, is generated and used as the script's name. To eliminate any possibility of name clashes, you can specify your own name instead.

Returns: string|resource The contents of the file as a string or as new PHP temp stream if the underlying Client::isStreamingResponses() is set to TRUE.

Exceptions

RouterErrorException When there's an error with the temporary script used to get the file, or if the file doesn't exist.

Definition at line 1142 of file Util.php.

◆ filePutContents()

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 position 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 1067 of file Util.php.

◆ find()

find ( )

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 427 of file Util.php.

◆ get()

get	(	$number,
		$valueName = `null`
	)

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

Parameters

int \| string \| null \| Query	$number	A number identifying the target item. 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. You can also specify a Query, in which case the first match will be considered the target item.
string \| resource \| null	$valueName	The name of the value to get. If omitted, or set to NULL, gets all properties of the target item.

Returns: string|resource|null|array The value of the specified property as a string or as new PHP temp stream if the underlying Client::isStreamingResponses() is set to TRUE. If the property is not set, NULL will be returned. If $valueName is NULL, returns all properties as an array, where the result is parsed with Script::parseValueToArray().

Exceptions

RouterErrorException When the router returns an error response (e.g. no such item, invalid property, etc.).

Definition at line 539 of file Util.php.

◆ getAll()

getAll	(	array	$args = `array()`,
		Query	$query = `null`
	)

Gets all items in the current menu.

Gets all items in the current menu, using a print request.

Parameters

	array<string,string\|resource>\|array<int,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. The "follow" and "follow-only" arguments are prohibited, as they would cause a synchronous request to run forever, without allowing the results to be observed. If you need to use those arguments, use static::newRequest(), and pass the resulting Request to Client::sendAsync(). The "count-only" argument is also prohibited, as results from it would not be consumable. Use static::count() for that.
Query \| null	$query	A query to filter items by. NULL to get all items.

Returns: ResponseCollection A response collection with all Response::TYPE_DATA responses. The collection will be empty when there are no matching items.

Exceptions

NotSupportedException	If $args contains prohibited arguments ("follow", "follow-only" or "count-only").
RouterErrorException	When there's an error upon attempting to call the "print" command on the specified menu (e.g. if there's no "print" command at the menu to begin with).

Definition at line 1002 of file Util.php.

◆ getCurrentTime()

getCurrentTime ( )

Gets the current time on the router.

Gets the current time on the router, regardless of the current menu.

If the timezone is one known to both RouterOS and PHP, it will be used as the timezone identifier. Otherwise (e.g. "manual"), the current GMT offset will be used as a timezone, without any DST awareness.

Returns: DateTime The current time of the router, as a DateTime object.

Definition at line 367 of file Util.php.

◆ getMenu()

getMenu ( )

Gets the current menu.

Returns: string The absolute path to current menu, using API syntax.

Definition at line 109 of file Util.php.

◆ move()

move	(	$numbers,
		$destination = `null`
	)

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. If NULL is given (or this argument is omitted), the targeted items will be moved to the bottom of the menu.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 905 of file Util.php.

◆ newRequest()

newRequest	(		$command,
		array	$args = `array()`,
		Query	$query = `null`,
			$tag = `null`
	)

Creates a Request object.

Creates a Request object, with a command that's at the current menu. The request can then be sent using Client.

Parameters

string	$command	The command of the request, not including the menu. The request will have that command at the current menu.
array	$args	Arguments of 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.
Query \| null	$query	The Query of the request.
string \| null	$tag	The tag of the request.

Returns: Request The Request object.

Exceptions

NotSupportedException	On an attempt to call a command in a different menu using API syntax.
InvalidArgumentException	On an attempt to call a command in a different menu using CLI syntax.

Definition at line 185 of file Util.php.

◆ remove()

remove ( )

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 static::find() for a description of what criteria are accepted.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 658 of file Util.php.

◆ set()

set	(		$numbers,
		array	$newValues
	)

Sets new values.

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

Parameters

mixed	$numbers	Items to be modified. Can be any criteria accepted by static::find() or NULL in case the menu is one without items (e.g. "/system identity").
	array<string,string\|resource>\|array<int,string>	$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.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 739 of file Util.php.

◆ setMenu()

setMenu ( $newMenu )

Sets the current menu.

Parameters

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.

Returns: $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 also: static::clearIdCache()

Definition at line 129 of file Util.php.

◆ unsetValue()

unsetValue	(	$numbers,
		$valueName
	)

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.

Parameters

mixed	$numbers	Targeted items. Can be any criteria accepted by static::find().
string	$valueName	The name of the value you want to unset.

Returns: ResponseCollection Returns the response collection, allowing you to inspect the output. Current RouterOS versions don't return anything useful, but if future ones do, you can read it right away.

Exceptions

RouterErrorException When the router returns one or more errors.

Definition at line 804 of file Util.php.

The documentation for this class was generated from the following file:

PEAR2/Net/RouterOS/Util.php

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ add()

◆ clearIdCache()

◆ comment()

◆ count()

◆ disable()

◆ doBulk()

◆ edit()

◆ enable()

◆ exec()

◆ fileGetContents()

◆ filePutContents()

◆ find()

◆ get()

◆ getAll()

◆ getCurrentTime()

◆ getMenu()

◆ move()

◆ newRequest()

◆ remove()

◆ set()

◆ setMenu()

◆ unsetValue()