pear2 /
Net_RouterOS
Complex classes like Util often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use Util, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 65 | class Util implements Countable |
||
| 66 | { |
||
| 67 | /** |
||
| 68 | * @var Client The connection to wrap around. |
||
| 69 | */ |
||
| 70 | protected $client; |
||
| 71 | |||
| 72 | /** |
||
| 73 | * @var string The current menu. |
||
| 74 | */ |
||
| 75 | protected $menu = '/'; |
||
| 76 | |||
| 77 | /** |
||
| 78 | * @var array<int,string>|null An array with the numbers of items in |
||
| 79 | * the current menu as keys, and the corresponding IDs as values. |
||
| 80 | * NULL when the cache needs regenerating. |
||
| 81 | */ |
||
| 82 | protected $idCache = null; |
||
| 83 | |||
| 84 | /** |
||
| 85 | * Parses a value from a RouterOS scripting context. |
||
| 86 | * |
||
| 87 | * Turns a value from RouterOS into an equivalent PHP value, based on |
||
| 88 | * determining the type in the same way RouterOS would determine it for a |
||
| 89 | * literal. |
||
| 90 | * |
||
| 91 | * This method is intended to be the very opposite of |
||
| 92 | * {@link static::escapeValue()}. That is, results from that method, if |
||
| 93 | * given to this method, should produce equivalent results. |
||
| 94 | * |
||
| 95 | * For better usefulness, in addition to "actual" RouterOS types, a pseudo |
||
| 96 | * "date" type is also recognized, whenever the string is in the form |
||
| 97 | * "M/j/Y". |
||
| 98 | * |
||
| 99 | * @param string $value The value to be parsed. Must be a literal of a |
||
| 100 | * value, e.g. what {@link static::escapeValue()} will give you. |
||
| 101 | * |
||
| 102 | * @return mixed Depending on RouterOS type detected: |
||
| 103 | * - "nil" or "nothing" - NULL. |
||
| 104 | * - "number" - int or double for large values. |
||
| 105 | * - "bool" - a boolean. |
||
| 106 | * - "time" - a {@link DateInterval} object. |
||
| 107 | * - "array" - an array, with the values processed recursively. |
||
| 108 | * - "str" - a string. |
||
| 109 | * - "date" (pseudo type) - a DateTime object with the specified date, |
||
| 110 | * at midnight UTC time. |
||
| 111 | * - Unrecognized type - treated as an unquoted string. |
||
| 112 | */ |
||
| 113 | public static function parseValue($value) |
||
| 282 | |||
| 283 | /** |
||
| 284 | * Prepares a script. |
||
| 285 | * |
||
| 286 | * Prepares a script for eventual execution by prepending parameters as |
||
| 287 | * variables to it. |
||
| 288 | * |
||
| 289 | * This is particularly useful when you're creating scripts that you don't |
||
| 290 | * want to execute right now (as with {@link static::exec()}, but instead |
||
| 291 | * you want to store it for later execution, perhaps by supplying it to |
||
| 292 | * "/system scheduler". |
||
| 293 | * |
||
| 294 | * @param string|resource $source The source of the script, as a string |
||
| 295 | * or stream. If a stream is provided, reading starts from the current |
||
| 296 | * position to the end of the stream, and the pointer stays at the end |
||
| 297 | * after reading is done. |
||
| 298 | * @param array<string,mixed> $params An array of parameters to make |
||
| 299 | * available in the script as local variables. |
||
| 300 | * Variable names are array keys, and variable values are array values. |
||
| 301 | * Array values are automatically processed with |
||
| 302 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 303 | * processed in chunks, each with |
||
| 304 | * {@link static::escapeString()}. Processing starts from the current |
||
| 305 | * position to the end of the stream, and the stream's pointer stays at |
||
| 306 | * the end after reading is done. |
||
| 307 | * |
||
| 308 | * @return resource A new PHP temporary stream with the script as contents, |
||
| 309 | * with the pointer back at the start. |
||
| 310 | * |
||
| 311 | * @see static::appendScript() |
||
| 312 | */ |
||
| 313 | public static function prepareScript( |
||
| 322 | |||
| 323 | /** |
||
| 324 | * Appends a script. |
||
| 325 | * |
||
| 326 | * Appends a script to an existing stream. |
||
| 327 | * |
||
| 328 | * @param resource $stream An existing stream to write the |
||
| 329 | * resulting script to. |
||
| 330 | * @param string|resource $source The source of the script, as a string |
||
| 331 | * or stream. If a stream is provided, reading starts from the current |
||
| 332 | * position to the end of the stream, and the pointer stays at the end |
||
| 333 | * after reading is done. |
||
| 334 | * @param array<string,mixed> $params An array of parameters to make |
||
| 335 | * available in the script as local variables. |
||
| 336 | * Variable names are array keys, and variable values are array values. |
||
| 337 | * Array values are automatically processed with |
||
| 338 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 339 | * processed in chunks, each with |
||
| 340 | * {@link static::escapeString()}. Processing starts from the current |
||
| 341 | * position to the end of the stream, and the stream's pointer stays at |
||
| 342 | * the end after reading is done. |
||
| 343 | * |
||
| 344 | * @return int The number of bytes written to $stream is returned, |
||
| 345 | * and the pointer remains where it was after the write |
||
| 346 | * (i.e. it is not seeked back, even if seeking is supported). |
||
| 347 | */ |
||
| 348 | public static function appendScript( |
||
| 377 | |||
| 378 | /** |
||
| 379 | * Escapes a value for a RouterOS scripting context. |
||
| 380 | * |
||
| 381 | * Turns any native PHP value into an equivalent whole value that can be |
||
| 382 | * inserted as part of a RouterOS script. |
||
| 383 | * |
||
| 384 | * DateInterval objects will be casted to RouterOS' "time" type. |
||
| 385 | * |
||
| 386 | * DateTime objects will be casted to a string following the "M/d/Y H:i:s" |
||
| 387 | * format. If the time is exactly midnight (including microseconds), and |
||
| 388 | * the timezone is UTC, the string will include only the "M/d/Y" date. |
||
| 389 | * |
||
| 390 | * Unrecognized types (i.e. resources and other objects) are casted to |
||
| 391 | * strings. |
||
| 392 | * |
||
| 393 | * @param mixed $value The value to be escaped. |
||
| 394 | * |
||
| 395 | * @return string A string representation that can be directly inserted in a |
||
| 396 | * script as a whole value. |
||
| 397 | */ |
||
| 398 | public static function escapeValue($value) |
||
| 448 | |||
| 449 | /** |
||
| 450 | * Escapes a string for a RouterOS scripting context. |
||
| 451 | * |
||
| 452 | * Escapes a string for a RouterOS scripting context. The value can then be |
||
| 453 | * surrounded with quotes at a RouterOS script (or concatenated onto a |
||
| 454 | * larger string first), and you can be sure there won't be any code |
||
| 455 | * injections coming from it. |
||
| 456 | * |
||
| 457 | * @param string $value Value to be escaped. |
||
| 458 | * |
||
| 459 | * @return string The escaped value. |
||
| 460 | */ |
||
| 461 | public static function escapeString($value) |
||
| 469 | |||
| 470 | /** |
||
| 471 | * Escapes a character for a RouterOS scripting context. |
||
| 472 | * |
||
| 473 | * Escapes a character for a RouterOS scripting context. Intended to only be |
||
| 474 | * called for non-alphanumeric characters. |
||
| 475 | * |
||
| 476 | * @param string $chars The matches array, expected to contain exactly one |
||
| 477 | * member, in which is the whole string to be escaped. |
||
| 478 | * |
||
| 479 | * @return string The escaped characters. |
||
| 480 | */ |
||
| 481 | private static function _escapeCharacters($chars) |
||
| 494 | |||
| 495 | /** |
||
| 496 | * Creates a new Util instance. |
||
| 497 | * |
||
| 498 | * Wraps around a connection to provide convenience methods. |
||
| 499 | * |
||
| 500 | * @param Client $client The connection to wrap around. |
||
| 501 | */ |
||
| 502 | public function __construct(Client $client) |
||
| 506 | |||
| 507 | /** |
||
| 508 | * Gets the current menu. |
||
| 509 | * |
||
| 510 | * @return string The absolute path to current menu, using API syntax. |
||
| 511 | */ |
||
| 512 | public function getMenu() |
||
| 516 | |||
| 517 | /** |
||
| 518 | * Sets the current menu. |
||
| 519 | * |
||
| 520 | * Sets the current menu. |
||
| 521 | * |
||
| 522 | * @param string $newMenu The menu to change to. Can be specified with API |
||
| 523 | * or CLI syntax and can be either absolute or relative. If relative, |
||
| 524 | * it's relative to the current menu, which by default is the root. |
||
| 525 | * |
||
| 526 | * @return $this The object itself. If an empty string is given for |
||
| 527 | * a new menu, no change is performed, |
||
| 528 | * but the ID cache is cleared anyway. |
||
| 529 | * |
||
| 530 | * @see static::clearIdCache() |
||
| 531 | */ |
||
| 532 | public function setMenu($newMenu) |
||
| 551 | |||
| 552 | /** |
||
| 553 | * Creates a Request object. |
||
| 554 | * |
||
| 555 | * Creates a {@link Request} object, with a command that's at the |
||
| 556 | * current menu. The request can then be sent using {@link Client}. |
||
| 557 | * |
||
| 558 | * @param string $command The command of the request, not including |
||
| 559 | * the menu. The request will have that command at the current menu. |
||
| 560 | * @param array $args Arguments of the request. |
||
| 561 | * Each array key is the name of the argument, and each array value is |
||
| 562 | * the value of the argument to be passed. |
||
| 563 | * Arguments without a value (i.e. empty arguments) can also be |
||
| 564 | * specified using a numeric key, and the name of the argument as the |
||
| 565 | * array value. |
||
| 566 | * @param Query|null $query The {@link Query} of the request. |
||
| 567 | * @param string|null $tag The tag of the request. |
||
| 568 | * |
||
| 569 | * @return Request The {@link Request} object. |
||
| 570 | * |
||
| 571 | * @throws NotSupportedException On an attempt to call a command in a |
||
| 572 | * different menu using API syntax. |
||
| 573 | * @throws InvalidArgumentException On an attempt to call a command in a |
||
| 574 | * different menu using CLI syntax. |
||
| 575 | */ |
||
| 576 | public function newRequest( |
||
| 601 | |||
| 602 | /** |
||
| 603 | * Executes a RouterOS script. |
||
| 604 | * |
||
| 605 | * Executes a RouterOS script, written as a string or a stream. |
||
| 606 | * Note that in cases of errors, the line numbers will be off, because the |
||
| 607 | * script is executed at the current menu as context, with the specified |
||
| 608 | * variables pre declared. This is achieved by prepending 1+count($params) |
||
| 609 | * lines before your actual script. |
||
| 610 | * |
||
| 611 | * @param string|resource $source The source of the script, as a string |
||
| 612 | * or stream. If a stream is provided, reading starts from the current |
||
| 613 | * position to the end of the stream, and the pointer stays at the end |
||
| 614 | * after reading is done. |
||
| 615 | * @param array<string,mixed> $params An array of parameters to make |
||
| 616 | * available in the script as local variables. |
||
| 617 | * Variable names are array keys, and variable values are array values. |
||
| 618 | * Array values are automatically processed with |
||
| 619 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 620 | * processed in chunks, each processed with |
||
| 621 | * {@link static::escapeString()}. Processing starts from the current |
||
| 622 | * position to the end of the stream, and the stream's pointer is left |
||
| 623 | * untouched after the reading is done. |
||
| 624 | * Note that the script's (generated) name is always added as the |
||
| 625 | * variable "_", which will be inadvertently lost if you overwrite it |
||
| 626 | * from here. |
||
| 627 | * @param string|null $policy Allows you to specify a policy the |
||
| 628 | * script must follow. Has the same format as in terminal. |
||
| 629 | * If left NULL, the script has no restrictions beyond those imposed by |
||
| 630 | * the username. |
||
| 631 | * @param string|null $name The script is executed after being |
||
| 632 | * saved in "/system script" and is removed after execution. |
||
| 633 | * If this argument is left NULL, a random string, |
||
| 634 | * prefixed with the computer's name, is generated and used |
||
| 635 | * as the script's name. |
||
| 636 | * To eliminate any possibility of name clashes, |
||
| 637 | * you can specify your own name instead. |
||
| 638 | * |
||
| 639 | * @return ResponseCollection Returns the response collection of the |
||
|
|
|||
| 640 | * run, allowing you to inspect errors, if any. |
||
| 641 | * If the script was not added successfully before execution, the |
||
| 642 | * ResponseCollection from the add attempt is going to be returned. |
||
| 643 | */ |
||
| 644 | public function exec( |
||
| 652 | |||
| 653 | /** |
||
| 654 | * Clears the ID cache. |
||
| 655 | * |
||
| 656 | * Normally, the ID cache improves performance when targeting items by a |
||
| 657 | * number. If you're using both Util's methods and other means (e.g. |
||
| 658 | * {@link Client} or {@link Util::exec()}) to add/move/remove items, the |
||
| 659 | * cache may end up being out of date. By calling this method right before |
||
| 660 | * targeting an item with a number, you can ensure number accuracy. |
||
| 661 | * |
||
| 662 | * Note that Util's {@link static::move()} and {@link static::remove()} |
||
| 663 | * methods automatically clear the cache before returning, while |
||
| 664 | * {@link static::add()} adds the new item's ID to the cache as the next |
||
| 665 | * number. A change in the menu also clears the cache. |
||
| 666 | * |
||
| 667 | * Note also that the cache is being rebuilt unconditionally every time you |
||
| 668 | * use {@link static::find()} with a callback. |
||
| 669 | * |
||
| 670 | * @return $this The Util object itself. |
||
| 671 | */ |
||
| 672 | public function clearIdCache() |
||
| 677 | |||
| 678 | /** |
||
| 679 | * Gets the current time on the router. |
||
| 680 | * |
||
| 681 | * Gets the current time on the router, regardless of the current menu. |
||
| 682 | * |
||
| 683 | * If the timezone is one known to both RouterOS and PHP, it will be used |
||
| 684 | * as the timezone identifier. Otherwise (e.g. "manual"), the current GMT |
||
| 685 | * offset will be used as a timezone, without any DST awareness. |
||
| 686 | * |
||
| 687 | * @return DateTime The current time of the router, as a DateTime object. |
||
| 688 | */ |
||
| 689 | public function getCurrentTime() |
||
| 728 | |||
| 729 | /** |
||
| 730 | * Finds the IDs of items at the current menu. |
||
| 731 | * |
||
| 732 | * Finds the IDs of items based on specified criteria, and returns them as |
||
| 733 | * a comma separated string, ready for insertion at a "numbers" argument. |
||
| 734 | * |
||
| 735 | * Accepts zero or more criteria as arguments. If zero arguments are |
||
| 736 | * specified, returns all items' IDs. The value of each criteria can be a |
||
| 737 | * number (just as in Winbox), a literal ID to be included, a {@link Query} |
||
| 738 | * object, or a callback. If a callback is specified, it is called for each |
||
| 739 | * item, with the item as an argument. If it returns a true value, the |
||
| 740 | * item's ID is included in the result. Every other value is casted to a |
||
| 741 | * string. A string is treated as a comma separated values of IDs, numbers |
||
| 742 | * or callback names. Non-existent callback names are instead placed in the |
||
| 743 | * result, which may be useful in menus that accept identifiers other than |
||
| 744 | * IDs, but note that it can cause errors on other menus. |
||
| 745 | * |
||
| 746 | * @return string A comma separated list of all items matching the |
||
| 747 | * specified criteria. |
||
| 748 | */ |
||
| 749 | public function find() |
||
| 835 | |||
| 836 | /** |
||
| 837 | * Gets a value of a specified item at the current menu. |
||
| 838 | * |
||
| 839 | * @param int|string|null $number A number identifying the item you're |
||
| 840 | * targeting. Can also be an ID or (in some menus) name. For menus where |
||
| 841 | * there are no items (e.g. "/system identity"), you can specify NULL. |
||
| 842 | * @param string $valueName The name of the value you want to get. |
||
| 843 | * |
||
| 844 | * @return string|resource|null|false The value of the specified property as |
||
| 845 | * a string or as new PHP temp stream if the underlying |
||
| 846 | * {@link Client::isStreamingResponses()} is set to TRUE. |
||
| 847 | * If the property is not set, NULL will be returned. FALSE on failure |
||
| 848 | * (e.g. no such item, invalid property, etc.). |
||
| 849 | */ |
||
| 850 | public function get($number, $valueName) |
||
| 895 | |||
| 896 | /** |
||
| 897 | * Enables all items at the current menu matching certain criteria. |
||
| 898 | * |
||
| 899 | * Zero or more arguments can be specified, each being a criteria. |
||
| 900 | * If zero arguments are specified, enables all items. |
||
| 901 | * See {@link static::find()} for a description of what criteria are |
||
| 902 | * accepted. |
||
| 903 | * |
||
| 904 | * @return ResponseCollection returns the response collection, allowing you |
||
| 905 | * to inspect errors, if any. |
||
| 906 | */ |
||
| 907 | public function enable() |
||
| 911 | |||
| 912 | /** |
||
| 913 | * Disables all items at the current menu matching certain criteria. |
||
| 914 | * |
||
| 915 | * Zero or more arguments can be specified, each being a criteria. |
||
| 916 | * If zero arguments are specified, disables all items. |
||
| 917 | * See {@link static::find()} for a description of what criteria are |
||
| 918 | * accepted. |
||
| 919 | * |
||
| 920 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 921 | * to inspect errors, if any. |
||
| 922 | */ |
||
| 923 | public function disable() |
||
| 927 | |||
| 928 | /** |
||
| 929 | * Removes all items at the current menu matching certain criteria. |
||
| 930 | * |
||
| 931 | * Zero or more arguments can be specified, each being a criteria. |
||
| 932 | * If zero arguments are specified, removes all items. |
||
| 933 | * See {@link static::find()} for a description of what criteria are |
||
| 934 | * accepted. |
||
| 935 | * |
||
| 936 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 937 | * to inspect errors, if any. |
||
| 938 | */ |
||
| 939 | public function remove() |
||
| 945 | |||
| 946 | /** |
||
| 947 | * Comments items. |
||
| 948 | * |
||
| 949 | * Sets new comments on all items at the current menu |
||
| 950 | * which match certain criteria, using the "comment" command. |
||
| 951 | * |
||
| 952 | * Note that not all menus have a "comment" command. Most notably, those are |
||
| 953 | * menus without items in them (e.g. "/system identity"), and menus with |
||
| 954 | * fixed items (e.g. "/ip service"). |
||
| 955 | * |
||
| 956 | * @param mixed $numbers Targeted items. Can be any criteria |
||
| 957 | * accepted by {@link static::find()}. |
||
| 958 | * @param string|resource $comment The new comment to set on the item as a |
||
| 959 | * string or a seekable stream. |
||
| 960 | * If a seekable stream is provided, it is sent from its current |
||
| 961 | * position to its end, and the pointer is seeked back to its current |
||
| 962 | * position after sending. |
||
| 963 | * Non seekable streams, as well as all other types, are casted to a |
||
| 964 | * string. |
||
| 965 | * |
||
| 966 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 967 | * to inspect errors, if any. |
||
| 968 | */ |
||
| 969 | public function comment($numbers, $comment) |
||
| 976 | |||
| 977 | /** |
||
| 978 | * Sets new values. |
||
| 979 | * |
||
| 980 | * Sets new values on certain properties on all items at the current menu |
||
| 981 | * which match certain criteria. |
||
| 982 | * |
||
| 983 | * @param mixed $numbers Items |
||
| 984 | * to be modified. |
||
| 985 | * Can be any criteria accepted by {@link static::find()} or NULL |
||
| 986 | * in case the menu is one without items (e.g. "/system identity"). |
||
| 987 | * @param array<string,string|resource>|array<int,string> $newValues An |
||
| 988 | * array with the names of each property to set as an array key, and the |
||
| 989 | * new value as an array value. |
||
| 990 | * Flags (properties with a value "true" that is interpreted as |
||
| 991 | * equivalent of "yes" from CLI) can also be specified with a numeric |
||
| 992 | * index as the array key, and the name of the flag as the array value. |
||
| 993 | * |
||
| 994 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 995 | * to inspect errors, if any. |
||
| 996 | */ |
||
| 997 | public function set($numbers, array $newValues) |
||
| 1012 | |||
| 1013 | /** |
||
| 1014 | * Alias of {@link static::set()} |
||
| 1015 | * |
||
| 1016 | * @param mixed $numbers Items to be modified. |
||
| 1017 | * Can be any criteria accepted by {@link static::find()} or NULL |
||
| 1018 | * in case the menu is one without items (e.g. "/system identity"). |
||
| 1019 | * @param string $valueName Name of property to be modified. |
||
| 1020 | * @param string|resource|null $newValue The new value to set. |
||
| 1021 | * If set to NULL, the property is unset. |
||
| 1022 | * |
||
| 1023 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1024 | * to inspect errors, if any. |
||
| 1025 | */ |
||
| 1026 | public function edit($numbers, $valueName, $newValue) |
||
| 1032 | |||
| 1033 | /** |
||
| 1034 | * Unsets a value of a specified item at the current menu. |
||
| 1035 | * |
||
| 1036 | * Equivalent of scripting's "unset" command. The "Value" part in the method |
||
| 1037 | * name is added because "unset" is a language construct, and thus a |
||
| 1038 | * reserved word. |
||
| 1039 | * |
||
| 1040 | * @param mixed $numbers Targeted items. Can be any criteria accepted |
||
| 1041 | * by {@link static::find()}. |
||
| 1042 | * @param string $valueName The name of the value you want to unset. |
||
| 1043 | * |
||
| 1044 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1045 | * to inspect errors, if any. |
||
| 1046 | */ |
||
| 1047 | public function unsetValue($numbers, $valueName) |
||
| 1055 | |||
| 1056 | /** |
||
| 1057 | * Adds a new item at the current menu. |
||
| 1058 | * |
||
| 1059 | * @param array<string,string|resource>|array<int,string> $values Accepts |
||
| 1060 | * one or more items to add to the current menu. |
||
| 1061 | * The data about each item is specified as an array with the names of |
||
| 1062 | * each property as an array key, and the value as an array value. |
||
| 1063 | * Flags (properties with a value "true" that is interpreted as |
||
| 1064 | * equivalent of "yes" from CLI) can also be specified with a numeric |
||
| 1065 | * index as the array key, and the name of the flag as the array value. |
||
| 1066 | * @param array<string,string|resource>|array<int,string> $... Additional |
||
| 1067 | * items. |
||
| 1068 | * |
||
| 1069 | * @return string A comma separated list of the new items' IDs. If a |
||
| 1070 | * particular item was not added, this will be indicated by an empty |
||
| 1071 | * string in its spot on the list. e.g. "*1D,,*1E" means that |
||
| 1072 | * you supplied three items to be added, of which the second one was |
||
| 1073 | * not added for some reason. |
||
| 1074 | */ |
||
| 1075 | public function add(array $values) |
||
| 1100 | |||
| 1101 | /** |
||
| 1102 | * Moves items at the current menu before a certain other item. |
||
| 1103 | * |
||
| 1104 | * Moves items before a certain other item. Note that the "move" |
||
| 1105 | * command is not available on all menus. As a rule of thumb, if the order |
||
| 1106 | * of items in a menu is irrelevant to their interpretation, there won't |
||
| 1107 | * be a move command on that menu. If in doubt, check from a terminal. |
||
| 1108 | * |
||
| 1109 | * @param mixed $numbers Targeted items. Can be any criteria accepted |
||
| 1110 | * by {@link static::find()}. |
||
| 1111 | * @param mixed $destination item before which the targeted items will be |
||
| 1112 | * moved to. Can be any criteria accepted by {@link static::find()}. |
||
| 1113 | * If multiple items match the criteria, the targeted items will move |
||
| 1114 | * above the first match. |
||
| 1115 | * |
||
| 1116 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1117 | * to inspect errors, if any. |
||
| 1118 | */ |
||
| 1119 | public function move($numbers, $destination) |
||
| 1131 | |||
| 1132 | /** |
||
| 1133 | * Counts items at the current menu. |
||
| 1134 | * |
||
| 1135 | * Counts items at the current menu. This executes a dedicated command |
||
| 1136 | * ("print" with a "count-only" argument) on RouterOS, which is why only |
||
| 1137 | * queries are allowed as a criteria, in contrast with |
||
| 1138 | * {@link static::find()}, where numbers and callbacks are allowed also. |
||
| 1139 | * |
||
| 1140 | * @param int $mode The counter mode. |
||
| 1141 | * Currently ignored, but present for compatibility with PHP 5.6+. |
||
| 1142 | * @param Query|null $query A query to filter items by. Without it, all items |
||
| 1143 | * are included in the count. |
||
| 1144 | * |
||
| 1145 | * @return int The number of items, or -1 on failure (e.g. if the |
||
| 1146 | * current menu does not have a "print" command or items to be counted). |
||
| 1147 | */ |
||
| 1148 | public function count($mode = COUNT_NORMAL, Query $query = null) |
||
| 1162 | |||
| 1163 | /** |
||
| 1164 | * Gets all items in the current menu. |
||
| 1165 | * |
||
| 1166 | * Gets all items in the current menu, using a print request. |
||
| 1167 | * |
||
| 1168 | * @param array<string,string|resource>|array<int,string> $args Additional |
||
| 1169 | * arguments to pass to the request. |
||
| 1170 | * Each array key is the name of the argument, and each array value is |
||
| 1171 | * the value of the argument to be passed. |
||
| 1172 | * Arguments without a value (i.e. empty arguments) can also be |
||
| 1173 | * specified using a numeric key, and the name of the argument as the |
||
| 1174 | * array value. |
||
| 1175 | * The "follow" and "follow-only" arguments are prohibited, |
||
| 1176 | * as they would cause a synchronous request to run forever, without |
||
| 1177 | * allowing the results to be observed. |
||
| 1178 | * If you need to use those arguments, use {@link static::newRequest()}, |
||
| 1179 | * and pass the resulting {@link Request} to {@link Client::sendAsync()}. |
||
| 1180 | * @param Query|null $query A query to |
||
| 1181 | * filter items by. |
||
| 1182 | * NULL to get all items. |
||
| 1183 | * |
||
| 1184 | * @return ResponseCollection|false A response collection with all |
||
| 1185 | * {@link Response::TYPE_DATA} responses. The collection will be empty |
||
| 1186 | * when there are no matching items. FALSE on failure. |
||
| 1187 | * |
||
| 1188 | * @throws NotSupportedException If $args contains prohibited arguments |
||
| 1189 | * ("follow" or "follow-only"). |
||
| 1190 | */ |
||
| 1191 | public function getAll(array $args = array(), Query $query = null) |
||
| 1219 | |||
| 1220 | /** |
||
| 1221 | * Puts a file on RouterOS's file system. |
||
| 1222 | * |
||
| 1223 | * Puts a file on RouterOS's file system, regardless of the current menu. |
||
| 1224 | * Note that this is a **VERY VERY VERY** time consuming method - it takes a |
||
| 1225 | * minimum of a little over 4 seconds, most of which are in sleep. It waits |
||
| 1226 | * 2 seconds after a file is first created (required to actually start |
||
| 1227 | * writing to the file), and another 2 seconds after its contents is written |
||
| 1228 | * (performed in order to verify success afterwards). |
||
| 1229 | * Similarly for removal (when $data is NULL) - there are two seconds in |
||
| 1230 | * sleep, used to verify the file was really deleted. |
||
| 1231 | * |
||
| 1232 | * If you want an efficient way of transferring files, use (T)FTP. |
||
| 1233 | * If you want an efficient way of removing files, use |
||
| 1234 | * {@link static::setMenu()} to move to the "/file" menu, and call |
||
| 1235 | * {@link static::remove()} without performing verification afterwards. |
||
| 1236 | * |
||
| 1237 | * @param string $filename The filename to write data in. |
||
| 1238 | * @param string|resource|null $data The data the file is going to have |
||
| 1239 | * as a string or a seekable stream. |
||
| 1240 | * Setting the value to NULL removes a file of this name. |
||
| 1241 | * If a seekable stream is provided, it is sent from its current |
||
| 1242 | * position to its end, and the pointer is seeked back to its current |
||
| 1243 | * position after sending. |
||
| 1244 | * Non seekable streams, as well as all other types, are casted to a |
||
| 1245 | * string. |
||
| 1246 | * @param bool $overwrite Whether to overwrite the file if |
||
| 1247 | * it exists. |
||
| 1248 | * |
||
| 1249 | * @return bool TRUE on success, FALSE on failure. |
||
| 1250 | */ |
||
| 1251 | public function filePutContents($filename, $data, $overwrite = false) |
||
| 1303 | |||
| 1304 | /** |
||
| 1305 | * Gets the contents of a specified file. |
||
| 1306 | * |
||
| 1307 | * @param string $filename The name of the file to get |
||
| 1308 | * the contents of. |
||
| 1309 | * @param string|null $tmpScriptName In order to get the file's contents, a |
||
| 1310 | * script is created at "/system script", the source of which is then |
||
| 1311 | * overwritten with the file's contents, then retrieved from there, |
||
| 1312 | * after which the script is removed. |
||
| 1313 | * If this argument is left NULL, a random string, |
||
| 1314 | * prefixed with the computer's name, is generated and used |
||
| 1315 | * as the script's name. |
||
| 1316 | * To eliminate any possibility of name clashes, |
||
| 1317 | * you can specify your own name instead. |
||
| 1318 | * |
||
| 1319 | * @return string|resource|false The contents of the file as a string or as |
||
| 1320 | * new PHP temp stream if the underlying |
||
| 1321 | * {@link Client::isStreamingResponses()} is set to TRUE. |
||
| 1322 | * FALSE is returned if there is no such file. |
||
| 1323 | */ |
||
| 1324 | public function fileGetContents($filename, $tmpScriptName = null) |
||
| 1342 | |||
| 1343 | /** |
||
| 1344 | * Performs an action on a bulk of items at the current menu. |
||
| 1345 | * |
||
| 1346 | * @param string $what What action to perform. |
||
| 1347 | * @param array $args Zero or more arguments can be specified, each being |
||
| 1348 | * a criteria. If zero arguments are specified, removes all items. |
||
| 1349 | * See {@link static::find()} for a description of what criteria are |
||
| 1350 | * accepted. |
||
| 1351 | * |
||
| 1352 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1353 | * to inspect errors, if any. |
||
| 1354 | */ |
||
| 1355 | protected function doBulk($what, array $args = array()) |
||
| 1364 | |||
| 1365 | /** |
||
| 1366 | * Executes a RouterOS script. |
||
| 1367 | * |
||
| 1368 | * Same as the public equivalent, with the addition of allowing you to get |
||
| 1369 | * the contents of the script post execution, instead of removing it. |
||
| 1370 | * |
||
| 1371 | * @param string|resource $source The source of the script, as a string |
||
| 1372 | * or stream. If a stream is provided, reading starts from the current |
||
| 1373 | * position to the end of the stream, and the pointer stays at the end |
||
| 1374 | * after reading is done. |
||
| 1375 | * @param array<string,mixed> $params An array of parameters to make |
||
| 1376 | * available in the script as local variables. |
||
| 1377 | * Variable names are array keys, and variable values are array values. |
||
| 1378 | * Array values are automatically processed with |
||
| 1379 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 1380 | * processed in chunks, each processed with |
||
| 1381 | * {@link static::escapeString()}. Processing starts from the current |
||
| 1382 | * position to the end of the stream, and the stream's pointer is left |
||
| 1383 | * untouched after the reading is done. |
||
| 1384 | * Note that the script's (generated) name is always added as the |
||
| 1385 | * variable "_", which will be inadvertently lost if you overwrite it |
||
| 1386 | * from here. |
||
| 1387 | * @param string|null $policy Allows you to specify a policy the |
||
| 1388 | * script must follow. Has the same format as in terminal. |
||
| 1389 | * If left NULL, the script has no restrictions beyond those imposed by |
||
| 1390 | * the username. |
||
| 1391 | * @param string|null $name The script is executed after being |
||
| 1392 | * saved in "/system script" and is removed after execution. |
||
| 1393 | * If this argument is left NULL, a random string, |
||
| 1394 | * prefixed with the computer's name, is generated and used |
||
| 1395 | * as the script's name. |
||
| 1396 | * To eliminate any possibility of name clashes, |
||
| 1397 | * you can specify your own name instead. |
||
| 1398 | * @param bool $get Whether to get the source |
||
| 1399 | * of the script. |
||
| 1400 | * |
||
| 1401 | * @return ResponseCollection|string Returns the response collection of the |
||
| 1402 | * run, allowing you to inspect errors, if any. |
||
| 1403 | * If the script was not added successfully before execution, the |
||
| 1404 | * ResponseCollection from the add attempt is going to be returned. |
||
| 1405 | * If $get is TRUE, returns the source of the script on success. |
||
| 1406 | */ |
||
| 1407 | private function _exec( |
||
| 1455 | } |
||
| 1456 |
Loading history...
This check compares the return type specified in the
@returnannotation of a function or method doc comment with the types returned by the function and raises an issue if they mismatch.