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) |
||
| 275 | |||
| 276 | /** |
||
| 277 | * Prepares a script. |
||
| 278 | * |
||
| 279 | * Prepares a script for eventual execution by prepending parameters as |
||
| 280 | * variables to it. |
||
| 281 | * |
||
| 282 | * This is particularly useful when you're creating scripts that you don't |
||
| 283 | * want to execute right now (as with {@link static::exec()}, but instead |
||
| 284 | * you want to store it for later execution, perhaps by supplying it to |
||
| 285 | * "/system scheduler". |
||
| 286 | * |
||
| 287 | * @param string|resource $source The source of the script, as a string |
||
| 288 | * or stream. If a stream is provided, reading starts from the current |
||
| 289 | * position to the end of the stream, and the pointer stays at the end |
||
| 290 | * after reading is done. |
||
| 291 | * @param array<string,mixed> $params An array of parameters to make |
||
| 292 | * available in the script as local variables. |
||
| 293 | * Variable names are array keys, and variable values are array values. |
||
| 294 | * Array values are automatically processed with |
||
| 295 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 296 | * processed in chunks, each with |
||
| 297 | * {@link static::escapeString()}. Processing starts from the current |
||
| 298 | * position to the end of the stream, and the stream's pointer stays at |
||
| 299 | * the end after reading is done. |
||
| 300 | * |
||
| 301 | * @return resource A new PHP temporary stream with the script as contents, |
||
| 302 | * with the pointer back at the start. |
||
| 303 | * |
||
| 304 | * @see static::appendScript() |
||
| 305 | */ |
||
| 306 | public static function prepareScript( |
||
| 315 | |||
| 316 | /** |
||
| 317 | * Appends a script. |
||
| 318 | * |
||
| 319 | * Appends a script to an existing stream. |
||
| 320 | * |
||
| 321 | * @param resource $stream An existing stream to write the |
||
| 322 | * resulting script to. |
||
| 323 | * @param string|resource $source The source of the script, as a string |
||
| 324 | * or stream. If a stream is provided, reading starts from the current |
||
| 325 | * position to the end of the stream, and the pointer stays at the end |
||
| 326 | * after reading is done. |
||
| 327 | * @param array<string,mixed> $params An array of parameters to make |
||
| 328 | * available in the script as local variables. |
||
| 329 | * Variable names are array keys, and variable values are array values. |
||
| 330 | * Array values are automatically processed with |
||
| 331 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 332 | * processed in chunks, each with |
||
| 333 | * {@link static::escapeString()}. Processing starts from the current |
||
| 334 | * position to the end of the stream, and the stream's pointer stays at |
||
| 335 | * the end after reading is done. |
||
| 336 | * |
||
| 337 | * @return int The number of bytes written to $stream is returned, |
||
| 338 | * and the pointer remains where it was after the write |
||
| 339 | * (i.e. it is not seeked back, even if seeking is supported). |
||
| 340 | */ |
||
| 341 | public static function appendScript( |
||
| 370 | |||
| 371 | /** |
||
| 372 | * Escapes a value for a RouterOS scripting context. |
||
| 373 | * |
||
| 374 | * Turns any native PHP value into an equivalent whole value that can be |
||
| 375 | * inserted as part of a RouterOS script. |
||
| 376 | * |
||
| 377 | * DateTime and DateInterval objects will be casted to RouterOS' "time" |
||
| 378 | * type. A DateTime object will be converted to a time relative to the UNIX |
||
| 379 | * epoch time. Note that if a DateInterval does not have the "days" property |
||
| 380 | * ("a" in formatting), then its months and years will be ignored, because |
||
| 381 | * they can't be unambiguously converted to a "time" value. |
||
| 382 | * |
||
| 383 | * Unrecognized types (i.e. resources and other objects) are casted to |
||
| 384 | * strings. |
||
| 385 | * |
||
| 386 | * @param mixed $value The value to be escaped. |
||
| 387 | * |
||
| 388 | * @return string A string representation that can be directly inserted in a |
||
| 389 | * script as a whole value. |
||
| 390 | */ |
||
| 391 | public static function escapeValue($value) |
||
| 445 | |||
| 446 | /** |
||
| 447 | * Escapes a string for a RouterOS scripting context. |
||
| 448 | * |
||
| 449 | * Escapes a string for a RouterOS scripting context. The value can then be |
||
| 450 | * surrounded with quotes at a RouterOS script (or concatenated onto a |
||
| 451 | * larger string first), and you can be sure there won't be any code |
||
| 452 | * injections coming from it. |
||
| 453 | * |
||
| 454 | * @param string $value Value to be escaped. |
||
| 455 | * |
||
| 456 | * @return string The escaped value. |
||
| 457 | */ |
||
| 458 | public static function escapeString($value) |
||
| 466 | |||
| 467 | /** |
||
| 468 | * Escapes a character for a RouterOS scripting context. |
||
| 469 | * |
||
| 470 | * Escapes a character for a RouterOS scripting context. Intended to only be |
||
| 471 | * called for non-alphanumeric characters. |
||
| 472 | * |
||
| 473 | * @param string $chars The matches array, expected to contain exactly one |
||
| 474 | * member, in which is the whole string to be escaped. |
||
| 475 | * |
||
| 476 | * @return string The escaped characters. |
||
| 477 | */ |
||
| 478 | private static function _escapeCharacters($chars) |
||
| 491 | |||
| 492 | /** |
||
| 493 | * Creates a new Util instance. |
||
| 494 | * |
||
| 495 | * Wraps around a connection to provide convenience methods. |
||
| 496 | * |
||
| 497 | * @param Client $client The connection to wrap around. |
||
| 498 | */ |
||
| 499 | public function __construct(Client $client) |
||
| 503 | |||
| 504 | /** |
||
| 505 | * Gets the current menu. |
||
| 506 | * |
||
| 507 | * @return string The absolute path to current menu, using API syntax. |
||
| 508 | */ |
||
| 509 | public function getMenu() |
||
| 513 | |||
| 514 | /** |
||
| 515 | * Sets the current menu. |
||
| 516 | * |
||
| 517 | * Sets the current menu. |
||
| 518 | * |
||
| 519 | * @param string $newMenu The menu to change to. Can be specified with API |
||
| 520 | * or CLI syntax and can be either absolute or relative. If relative, |
||
| 521 | * it's relative to the current menu, which by default is the root. |
||
| 522 | * |
||
| 523 | * @return $this The object itself. If an empty string is given for |
||
| 524 | * a new menu, no change is performed, |
||
| 525 | * but the ID cache is cleared anyway. |
||
| 526 | * |
||
| 527 | * @see static::clearIdCache() |
||
| 528 | */ |
||
| 529 | public function setMenu($newMenu) |
||
| 548 | |||
| 549 | /** |
||
| 550 | * Creates a Request object. |
||
| 551 | * |
||
| 552 | * Creates a {@link Request} object, with a command that's at the |
||
| 553 | * current menu. The request can then be sent using {@link Client}. |
||
| 554 | * |
||
| 555 | * @param string $command The command of the request, not including |
||
| 556 | * the menu. The request will have that command at the current menu. |
||
| 557 | * @param array $args Arguments of the request. |
||
| 558 | * Each array key is the name of the argument, and each array value is |
||
| 559 | * the value of the argument to be passed. |
||
| 560 | * Arguments without a value (i.e. empty arguments) can also be |
||
| 561 | * specified using a numeric key, and the name of the argument as the |
||
| 562 | * array value. |
||
| 563 | * @param Query|null $query The {@link Query} of the request. |
||
| 564 | * @param string|null $tag The tag of the request. |
||
| 565 | * |
||
| 566 | * @return Request The {@link Request} object. |
||
| 567 | * |
||
| 568 | * @throws NotSupportedException On an attempt to call a command in a |
||
| 569 | * different menu using API syntax. |
||
| 570 | * @throws InvalidArgumentException On an attempt to call a command in a |
||
| 571 | * different menu using CLI syntax. |
||
| 572 | */ |
||
| 573 | public function newRequest( |
||
| 598 | |||
| 599 | /** |
||
| 600 | * Executes a RouterOS script. |
||
| 601 | * |
||
| 602 | * Executes a RouterOS script, written as a string or a stream. |
||
| 603 | * Note that in cases of errors, the line numbers will be off, because the |
||
| 604 | * script is executed at the current menu as context, with the specified |
||
| 605 | * variables pre declared. This is achieved by prepending 1+count($params) |
||
| 606 | * lines before your actual script. |
||
| 607 | * |
||
| 608 | * @param string|resource $source The source of the script, as a string |
||
| 609 | * or stream. If a stream is provided, reading starts from the current |
||
| 610 | * position to the end of the stream, and the pointer stays at the end |
||
| 611 | * after reading is done. |
||
| 612 | * @param array<string,mixed> $params An array of parameters to make |
||
| 613 | * available in the script as local variables. |
||
| 614 | * Variable names are array keys, and variable values are array values. |
||
| 615 | * Array values are automatically processed with |
||
| 616 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 617 | * processed in chunks, each processed with |
||
| 618 | * {@link static::escapeString()}. Processing starts from the current |
||
| 619 | * position to the end of the stream, and the stream's pointer is left |
||
| 620 | * untouched after the reading is done. |
||
| 621 | * Note that the script's (generated) name is always added as the |
||
| 622 | * variable "_", which will be inadvertently lost if you overwrite it |
||
| 623 | * from here. |
||
| 624 | * @param string|null $policy Allows you to specify a policy the |
||
| 625 | * script must follow. Has the same format as in terminal. |
||
| 626 | * If left NULL, the script has no restrictions beyond those imposed by |
||
| 627 | * the username. |
||
| 628 | * @param string|null $name The script is executed after being |
||
| 629 | * saved in "/system script" and is removed after execution. |
||
| 630 | * If this argument is left NULL, a random string, |
||
| 631 | * prefixed with the computer's name, is generated and used |
||
| 632 | * as the script's name. |
||
| 633 | * To eliminate any possibility of name clashes, |
||
| 634 | * you can specify your own name instead. |
||
| 635 | * |
||
| 636 | * @return ResponseCollection Returns the response collection of the |
||
| 637 | * run, allowing you to inspect errors, if any. |
||
| 638 | * If the script was not added successfully before execution, the |
||
| 639 | * ResponseCollection from the add attempt is going to be returned. |
||
| 640 | */ |
||
| 641 | public function exec( |
||
| 649 | |||
| 650 | /** |
||
| 651 | * Clears the ID cache. |
||
| 652 | * |
||
| 653 | * Normally, the ID cache improves performance when targeting items by a |
||
| 654 | * number. If you're using both Util's methods and other means (e.g. |
||
| 655 | * {@link Client} or {@link Util::exec()}) to add/move/remove items, the |
||
| 656 | * cache may end up being out of date. By calling this method right before |
||
| 657 | * targeting an item with a number, you can ensure number accuracy. |
||
| 658 | * |
||
| 659 | * Note that Util's {@link static::move()} and {@link static::remove()} |
||
| 660 | * methods automatically clear the cache before returning, while |
||
| 661 | * {@link static::add()} adds the new item's ID to the cache as the next |
||
| 662 | * number. A change in the menu also clears the cache. |
||
| 663 | * |
||
| 664 | * Note also that the cache is being rebuilt unconditionally every time you |
||
| 665 | * use {@link static::find()} with a callback. |
||
| 666 | * |
||
| 667 | * @return $this The Util object itself. |
||
| 668 | */ |
||
| 669 | public function clearIdCache() |
||
| 674 | |||
| 675 | /** |
||
| 676 | * Gets the current time on the router. |
||
| 677 | * |
||
| 678 | * Gets the current time on the router, regardless of the current menu. |
||
| 679 | * |
||
| 680 | * If your router uses a "manual" timezone, the resulting object will use |
||
| 681 | * the "gmt-offset" as the timezone identifier. |
||
| 682 | * |
||
| 683 | * @return DateTime The current time of the router, as a DateTime object. |
||
| 684 | */ |
||
| 685 | public function getCurrentTime() |
||
| 707 | |||
| 708 | /** |
||
| 709 | * Finds the IDs of items at the current menu. |
||
| 710 | * |
||
| 711 | * Finds the IDs of items based on specified criteria, and returns them as |
||
| 712 | * a comma separated string, ready for insertion at a "numbers" argument. |
||
| 713 | * |
||
| 714 | * Accepts zero or more criteria as arguments. If zero arguments are |
||
| 715 | * specified, returns all items' IDs. The value of each criteria can be a |
||
| 716 | * number (just as in Winbox), a literal ID to be included, a {@link Query} |
||
| 717 | * object, or a callback. If a callback is specified, it is called for each |
||
| 718 | * item, with the item as an argument. If it returns a true value, the |
||
| 719 | * item's ID is included in the result. Every other value is casted to a |
||
| 720 | * string. A string is treated as a comma separated values of IDs, numbers |
||
| 721 | * or callback names. Non-existent callback names are instead placed in the |
||
| 722 | * result, which may be useful in menus that accept identifiers other than |
||
| 723 | * IDs, but note that it can cause errors on other menus. |
||
| 724 | * |
||
| 725 | * @return string A comma separated list of all items matching the |
||
| 726 | * specified criteria. |
||
| 727 | */ |
||
| 728 | public function find() |
||
| 807 | |||
| 808 | /** |
||
| 809 | * Gets a value of a specified item at the current menu. |
||
| 810 | * |
||
| 811 | * @param int|string|null $number A number identifying the item you're |
||
| 812 | * targeting. Can also be an ID or (in some menus) name. For menus where |
||
| 813 | * there are no items (e.g. "/system identity"), you can specify NULL. |
||
| 814 | * @param string $valueName The name of the value you want to get. |
||
| 815 | * |
||
| 816 | * @return string|resource|null|false The value of the specified property as |
||
| 817 | * a string or as new PHP temp stream if the underlying |
||
| 818 | * {@link Client::isStreamingResponses()} is set to TRUE. |
||
| 819 | * If the property is not set, NULL will be returned. FALSE on failure |
||
| 820 | * (e.g. no such item, invalid property, etc.). |
||
| 821 | */ |
||
| 822 | public function get($number, $valueName) |
||
| 867 | |||
| 868 | /** |
||
| 869 | * Enables all items at the current menu matching certain criteria. |
||
| 870 | * |
||
| 871 | * Zero or more arguments can be specified, each being a criteria. |
||
| 872 | * If zero arguments are specified, enables all items. |
||
| 873 | * See {@link static::find()} for a description of what criteria are |
||
| 874 | * accepted. |
||
| 875 | * |
||
| 876 | * @return ResponseCollection returns the response collection, allowing you |
||
| 877 | * to inspect errors, if any. |
||
| 878 | */ |
||
| 879 | public function enable() |
||
| 883 | |||
| 884 | /** |
||
| 885 | * Disables all items at the current menu matching certain criteria. |
||
| 886 | * |
||
| 887 | * Zero or more arguments can be specified, each being a criteria. |
||
| 888 | * If zero arguments are specified, disables all items. |
||
| 889 | * See {@link static::find()} for a description of what criteria are |
||
| 890 | * accepted. |
||
| 891 | * |
||
| 892 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 893 | * to inspect errors, if any. |
||
| 894 | */ |
||
| 895 | public function disable() |
||
| 899 | |||
| 900 | /** |
||
| 901 | * Removes all items at the current menu matching certain criteria. |
||
| 902 | * |
||
| 903 | * Zero or more arguments can be specified, each being a criteria. |
||
| 904 | * If zero arguments are specified, removes all items. |
||
| 905 | * See {@link static::find()} for a description of what criteria are |
||
| 906 | * accepted. |
||
| 907 | * |
||
| 908 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 909 | * to inspect errors, if any. |
||
| 910 | */ |
||
| 911 | public function remove() |
||
| 917 | |||
| 918 | /** |
||
| 919 | * Comments items. |
||
| 920 | * |
||
| 921 | * Sets new comments on all items at the current menu |
||
| 922 | * which match certain criteria, using the "comment" command. |
||
| 923 | * |
||
| 924 | * Note that not all menus have a "comment" command. Most notably, those are |
||
| 925 | * menus without items in them (e.g. "/system identity"), and menus with |
||
| 926 | * fixed items (e.g. "/ip service"). |
||
| 927 | * |
||
| 928 | * @param mixed $numbers Targeted items. Can be any criteria |
||
| 929 | * accepted by {@link static::find()}. |
||
| 930 | * @param string|resource $comment The new comment to set on the item as a |
||
| 931 | * string or a seekable stream. |
||
| 932 | * If a seekable stream is provided, it is sent from its current |
||
| 933 | * position to its end, and the pointer is seeked back to its current |
||
| 934 | * position after sending. |
||
| 935 | * Non seekable streams, as well as all other types, are casted to a |
||
| 936 | * string. |
||
| 937 | * |
||
| 938 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 939 | * to inspect errors, if any. |
||
| 940 | */ |
||
| 941 | public function comment($numbers, $comment) |
||
| 948 | |||
| 949 | /** |
||
| 950 | * Sets new values. |
||
| 951 | * |
||
| 952 | * Sets new values on certain properties on all items at the current menu |
||
| 953 | * which match certain criteria. |
||
| 954 | * |
||
| 955 | * @param mixed $numbers Items |
||
| 956 | * to be modified. |
||
| 957 | * Can be any criteria accepted by {@link static::find()} or NULL |
||
| 958 | * in case the menu is one without items (e.g. "/system identity"). |
||
| 959 | * @param array<string,string|resource>|array<int,string> $newValues An |
||
| 960 | * array with the names of each property to set as an array key, and the |
||
| 961 | * new value as an array value. |
||
| 962 | * Flags (properties with a value "true" that is interpreted as |
||
| 963 | * equivalent of "yes" from CLI) can also be specified with a numeric |
||
| 964 | * index as the array key, and the name of the flag as the array value. |
||
| 965 | * |
||
| 966 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 967 | * to inspect errors, if any. |
||
| 968 | */ |
||
| 969 | public function set($numbers, array $newValues) |
||
| 984 | |||
| 985 | /** |
||
| 986 | * Alias of {@link static::set()} |
||
| 987 | * |
||
| 988 | * @param mixed $numbers Items |
||
| 989 | * to be modified. |
||
| 990 | * Can be any criteria accepted by {@link static::find()} or NULL |
||
| 991 | * in case the menu is one without items (e.g. "/system identity"). |
||
| 992 | * @param array<string,string|resource>|array<int,string> $newValues An |
||
| 993 | * array with the names of each property to set as an array key, and the |
||
| 994 | * new value as an array value. |
||
| 995 | * |
||
| 996 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 997 | * to inspect errors, if any. |
||
| 998 | */ |
||
| 999 | public function edit($numbers, array $newValues) |
||
| 1003 | |||
| 1004 | /** |
||
| 1005 | * Unsets a value of a specified item at the current menu. |
||
| 1006 | * |
||
| 1007 | * Equivalent of scripting's "unset" command. The "Value" part in the method |
||
| 1008 | * name is added because "unset" is a language construct, and thus a |
||
| 1009 | * reserved word. |
||
| 1010 | * |
||
| 1011 | * @param mixed $numbers Targeted items. Can be any criteria accepted |
||
| 1012 | * by {@link static::find()}. |
||
| 1013 | * @param string $valueName The name of the value you want to unset. |
||
| 1014 | * |
||
| 1015 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1016 | * to inspect errors, if any. |
||
| 1017 | */ |
||
| 1018 | public function unsetValue($numbers, $valueName) |
||
| 1026 | |||
| 1027 | /** |
||
| 1028 | * Adds a new item at the current menu. |
||
| 1029 | * |
||
| 1030 | * @param array<string,string|resource>|array<int,string> $values Accepts |
||
| 1031 | * one or more items to add to the current menu. |
||
| 1032 | * The data about each item is specified as an array with the names of |
||
| 1033 | * each property as an array key, and the value as an array value. |
||
| 1034 | * Flags (properties with a value "true" that is interpreted as |
||
| 1035 | * equivalent of "yes" from CLI) can also be specified with a numeric |
||
| 1036 | * index as the array key, and the name of the flag as the array value. |
||
| 1037 | * @param array<string,string|resource>|array<int,string> $... Additional |
||
| 1038 | * items. |
||
| 1039 | * |
||
| 1040 | * @return string A comma separated list of the new items' IDs. If a |
||
| 1041 | * particular item was not added, this will be indicated by an empty |
||
| 1042 | * string in its spot on the list. e.g. "*1D,,*1E" means that |
||
| 1043 | * you supplied three items to be added, of which the second one was |
||
| 1044 | * not added for some reason. |
||
| 1045 | */ |
||
| 1046 | public function add(array $values) |
||
| 1071 | |||
| 1072 | /** |
||
| 1073 | * Moves items at the current menu before a certain other item. |
||
| 1074 | * |
||
| 1075 | * Moves items before a certain other item. Note that the "move" |
||
| 1076 | * command is not available on all menus. As a rule of thumb, if the order |
||
| 1077 | * of items in a menu is irrelevant to their interpretation, there won't |
||
| 1078 | * be a move command on that menu. If in doubt, check from a terminal. |
||
| 1079 | * |
||
| 1080 | * @param mixed $numbers Targeted items. Can be any criteria accepted |
||
| 1081 | * by {@link static::find()}. |
||
| 1082 | * @param mixed $destination item before which the targeted items will be |
||
| 1083 | * moved to. Can be any criteria accepted by {@link static::find()}. |
||
| 1084 | * If multiple items match the criteria, the targeted items will move |
||
| 1085 | * above the first match. |
||
| 1086 | * |
||
| 1087 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1088 | * to inspect errors, if any. |
||
| 1089 | */ |
||
| 1090 | public function move($numbers, $destination) |
||
| 1102 | |||
| 1103 | /** |
||
| 1104 | * Counts items at the current menu. |
||
| 1105 | * |
||
| 1106 | * Counts items at the current menu. This executes a dedicated command |
||
| 1107 | * ("print" with a "count-only" argument) on RouterOS, which is why only |
||
| 1108 | * queries are allowed as a criteria, in contrast with |
||
| 1109 | * {@link static::find()}, where numbers and callbacks are allowed also. |
||
| 1110 | * |
||
| 1111 | * @param int $mode The counter mode. |
||
| 1112 | * Currently ignored, but present for compatibility with PHP 5.6+. |
||
| 1113 | * @param Query|null $query A query to filter items by. Without it, all items |
||
| 1114 | * are included in the count. |
||
| 1115 | * |
||
| 1116 | * @return int The number of items, or -1 on failure (e.g. if the |
||
| 1117 | * current menu does not have a "print" command or items to be counted). |
||
| 1118 | */ |
||
| 1119 | public function count($mode = COUNT_NORMAL, Query $query = null) |
||
| 1133 | |||
| 1134 | /** |
||
| 1135 | * Gets all items in the current menu. |
||
| 1136 | * |
||
| 1137 | * Gets all items in the current menu, using a print request. |
||
| 1138 | * |
||
| 1139 | * @param array<string,string|resource>|array<int,string> $args Additional |
||
| 1140 | * arguments to pass to the request. |
||
| 1141 | * Each array key is the name of the argument, and each array value is |
||
| 1142 | * the value of the argument to be passed. |
||
| 1143 | * Arguments without a value (i.e. empty arguments) can also be |
||
| 1144 | * specified using a numeric key, and the name of the argument as the |
||
| 1145 | * array value. |
||
| 1146 | * The "follow" and "follow-only" arguments are prohibited, |
||
| 1147 | * as they would cause a synchronous request to run forever, without |
||
| 1148 | * allowing the results to be observed. |
||
| 1149 | * If you need to use those arguments, use {@link static::newRequest()}, |
||
| 1150 | * and pass the resulting {@link Request} to {@link Client::sendAsync()}. |
||
| 1151 | * @param Query|null $query A query to |
||
| 1152 | * filter items by. |
||
| 1153 | * NULL to get all items. |
||
| 1154 | * |
||
| 1155 | * @return ResponseCollection|false A response collection with all |
||
| 1156 | * {@link Response::TYPE_DATA} responses. The collection will be empty |
||
| 1157 | * when there are no matching items. FALSE on failure. |
||
| 1158 | * |
||
| 1159 | * @throws NotSupportedException If $args contains prohibited arguments |
||
| 1160 | * ("follow" or "follow-only"). |
||
| 1161 | */ |
||
| 1162 | public function getAll(array $args = array(), Query $query = null) |
||
| 1187 | |||
| 1188 | /** |
||
| 1189 | * Puts a file on RouterOS's file system. |
||
| 1190 | * |
||
| 1191 | * Puts a file on RouterOS's file system, regardless of the current menu. |
||
| 1192 | * Note that this is a **VERY VERY VERY** time consuming method - it takes a |
||
| 1193 | * minimum of a little over 4 seconds, most of which are in sleep. It waits |
||
| 1194 | * 2 seconds after a file is first created (required to actually start |
||
| 1195 | * writing to the file), and another 2 seconds after its contents is written |
||
| 1196 | * (performed in order to verify success afterwards). |
||
| 1197 | * Similarly for removal (when $data is NULL) - there are two seconds in |
||
| 1198 | * sleep, used to verify the file was really deleted. |
||
| 1199 | * |
||
| 1200 | * If you want an efficient way of transferring files, use (T)FTP. |
||
| 1201 | * If you want an efficient way of removing files, use |
||
| 1202 | * {@link static::setMenu()} to move to the "/file" menu, and call |
||
| 1203 | * {@link static::remove()} without performing verification afterwards. |
||
| 1204 | * |
||
| 1205 | * @param string $filename The filename to write data in. |
||
| 1206 | * @param string|resource|null $data The data the file is going to have |
||
| 1207 | * as a string or a seekable stream. |
||
| 1208 | * Setting the value to NULL removes a file of this name. |
||
| 1209 | * If a seekable stream is provided, it is sent from its current |
||
| 1210 | * position to its end, and the pointer is seeked back to its current |
||
| 1211 | * position after sending. |
||
| 1212 | * Non seekable streams, as well as all other types, are casted to a |
||
| 1213 | * string. |
||
| 1214 | * @param bool $overwrite Whether to overwrite the file if |
||
| 1215 | * it exists. |
||
| 1216 | * |
||
| 1217 | * @return bool TRUE on success, FALSE on failure. |
||
| 1218 | */ |
||
| 1219 | public function filePutContents($filename, $data, $overwrite = false) |
||
| 1271 | |||
| 1272 | /** |
||
| 1273 | * Gets the contents of a specified file. |
||
| 1274 | * |
||
| 1275 | * @param string $filename The name of the file to get |
||
| 1276 | * the contents of. |
||
| 1277 | * @param string|null $tmpScriptName In order to get the file's contents, a |
||
| 1278 | * script is created at "/system script", the source of which is then |
||
| 1279 | * overwritten with the file's contents, then retrieved from there, |
||
| 1280 | * after which the script is removed. |
||
| 1281 | * If this argument is left NULL, a random string, |
||
| 1282 | * prefixed with the computer's name, is generated and used |
||
| 1283 | * as the script's name. |
||
| 1284 | * To eliminate any possibility of name clashes, |
||
| 1285 | * you can specify your own name instead. |
||
| 1286 | * |
||
| 1287 | * @return string|resource|false The contents of the file as a string or as |
||
| 1288 | * new PHP temp stream if the underlying |
||
| 1289 | * {@link Client::isStreamingResponses()} is set to TRUE. |
||
| 1290 | * FALSE is returned if there is no such file. |
||
| 1291 | */ |
||
| 1292 | public function fileGetContents($filename, $tmpScriptName = null) |
||
| 1310 | |||
| 1311 | /** |
||
| 1312 | * Performs an action on a bulk of items at the current menu. |
||
| 1313 | * |
||
| 1314 | * @param string $what What action to perform. |
||
| 1315 | * @param array $args Zero or more arguments can be specified, each being |
||
| 1316 | * a criteria. If zero arguments are specified, removes all items. |
||
| 1317 | * See {@link static::find()} for a description of what criteria are |
||
| 1318 | * accepted. |
||
| 1319 | * |
||
| 1320 | * @return ResponseCollection Returns the response collection, allowing you |
||
| 1321 | * to inspect errors, if any. |
||
| 1322 | */ |
||
| 1323 | protected function doBulk($what, array $args = array()) |
||
| 1332 | |||
| 1333 | /** |
||
| 1334 | * Executes a RouterOS script. |
||
| 1335 | * |
||
| 1336 | * Same as the public equivalent, with the addition of allowing you to get |
||
| 1337 | * the contents of the script post execution, instead of removing it. |
||
| 1338 | * |
||
| 1339 | * @param string|resource $source The source of the script, as a string |
||
| 1340 | * or stream. If a stream is provided, reading starts from the current |
||
| 1341 | * position to the end of the stream, and the pointer stays at the end |
||
| 1342 | * after reading is done. |
||
| 1343 | * @param array<string,mixed> $params An array of parameters to make |
||
| 1344 | * available in the script as local variables. |
||
| 1345 | * Variable names are array keys, and variable values are array values. |
||
| 1346 | * Array values are automatically processed with |
||
| 1347 | * {@link static::escapeValue()}. Streams are also supported, and are |
||
| 1348 | * processed in chunks, each processed with |
||
| 1349 | * {@link static::escapeString()}. Processing starts from the current |
||
| 1350 | * position to the end of the stream, and the stream's pointer is left |
||
| 1351 | * untouched after the reading is done. |
||
| 1352 | * Note that the script's (generated) name is always added as the |
||
| 1353 | * variable "_", which will be inadvertently lost if you overwrite it |
||
| 1354 | * from here. |
||
| 1355 | * @param string|null $policy Allows you to specify a policy the |
||
| 1356 | * script must follow. Has the same format as in terminal. |
||
| 1357 | * If left NULL, the script has no restrictions beyond those imposed by |
||
| 1358 | * the username. |
||
| 1359 | * @param string|null $name The script is executed after being |
||
| 1360 | * saved in "/system script" and is removed after execution. |
||
| 1361 | * If this argument is left NULL, a random string, |
||
| 1362 | * prefixed with the computer's name, is generated and used |
||
| 1363 | * as the script's name. |
||
| 1364 | * To eliminate any possibility of name clashes, |
||
| 1365 | * you can specify your own name instead. |
||
| 1366 | * @param bool $get Whether to get the source |
||
| 1367 | * of the script. |
||
| 1368 | * |
||
| 1369 | * @return ResponseCollection|string Returns the response collection of the |
||
| 1370 | * run, allowing you to inspect errors, if any. |
||
| 1371 | * If the script was not added successfully before execution, the |
||
| 1372 | * ResponseCollection from the add attempt is going to be returned. |
||
| 1373 | * If $get is TRUE, returns the source of the script on success. |
||
| 1374 | */ |
||
| 1375 | private function _exec( |
||
| 1423 | } |
||
| 1424 |
Loading history...
If a method or function can return multiple different values and unless you are sure that you only can receive a single value in this context, we recommend to add an additional type check:
If this a common case that PHP Analyzer should handle natively, please let us know by opening an issue.