Created RouterErrorException and made it be thrown by various Util methods (more to come);

Tweaked root menu storage (setMenu() and getMenu() more specifically), so that it allows Util::newRequest() from it properly;
Fixed Script::parseValueToArray() exception code;
Many other changes (see RELEASE-1.0.0b6 diff).

Author: boenrobot

RELEASE-1.0.0b6

@@ -1,6 +1,7 @@
 Util stuff, mostly.
 
 * __BREAKING CHANGES:__
+    - Removed all $mode arguments from all Countable implementations (turns out no stable 5.6+ releases uses it...), and the COUNT_RECURSIVE implementations (which were mostly useless anyway). Util::count() has the $query argument as its first and only one.
     - Util::edit() is no longer an alias of Util::set(). It's now its own method that can modify or unset a single specified property.
     - Util's escapeValue(), escapeString(), parseValue(), prepareScript() and appendScript() methods are now in their own new class called "Script", with the last two now being called just prepare() and append().
     - Script::escapeValue() now converts DateTime objects into a string having the "M/d/Y H:i:s" format (used across RouterOS), or just "M/d/Y" if the time is exactly midnight, and the timezone is UTC. The old behaviour can be achieved by "manually" adding the DateTime to "new DateTime('@0')".
@@ -10,8 +11,12 @@ Util stuff, mostly.
     - newRequest()
 * Script::parseValue() now supports letter notation for time (1h2m3s), not just double colon notation (01:02:03), modeled after RouterOS. Related to that is also that leading zeroes, and zero minutes and seconds are now optional (e.g. "1:" is a valid way of saying 1 hour). Sub-second information is rounded up to the nearest second on current PHP versions (future versions are expected to support sub-second information in DateInterval by allowing seconds to be a double; The code currently attempts to give DateInterval a double, falling back to rounding to a second).
 * Script::parseValue() now recognizes dates in the "M/d/Y H:i:s" format (used across RouterOS), and turns that into a DateTime object for that time (or midnight in UTC if the time part is omitted).
+* Util::exec() now returns the script source after execution. Previously, this was a private option, but is now the only way, and it's public. Intended to be used for easier output extraction.
 * Util::getAll() now throws a NotSupportedException if the arguments "follow", "follow-only" or "count-only" are used. The first two, because PHP would hang (since Client::sendSync() is used under the hood), and the last one because it's unredable in the returned output (use Util::count() instead).
 * Util::setMenu() can now go back to the root menu.
+* Util::get() can now accept a query as an argument for $number
+* Util::get() can have $valueName set to NULL (as is now by default), in which case all properties are retrieved in an array, parsed with Script::parseValueToArray().
+* Util::get() no longer fallbacks automatically with a "print" request for buggy versions. You may "manually" call Util::getAll() if you suspect that's an issue.
 * Util::find() now works even when the underlying Client streams responses.
 * Util::move()'s second argument $destination is now optional, and without it (or if set to NULL), the item is moved at the bottom of the menu.
 * Client::login() consumes the !done or !fatal response even when called on an already logged in connection.

src/PEAR2/Net/RouterOS/Message.php

@@ -181,24 +181,13 @@ public function getIterator()
     }
 
     /**
-     * Counts the number of arguments.
+     * Counts the number of attributes.
      *
-     * @param int $mode The counter mode.
-     *     Either COUNT_NORMAL or COUNT_RECURSIVE.
-     *     When in normal mode, counts the number of arguments.
-     *     When in recursive mode, counts the number of API words
-     *     (including the empty word at the end).
-     *
-     * @return int The number of arguments/words.
+     * @return int The number of attributes.
      */
-    public function count($mode = COUNT_NORMAL)
+    public function count()
     {
-        $result = count($this->attributes);
-        if ($mode !== COUNT_NORMAL) {
-            $result += 2/*first+last word*/
-                + (int)(null !== $this->getTag());
-        }
-        return $result;
+        return count($this->attributes);
     }
 
     /**

src/PEAR2/Net/RouterOS/Response.php

@@ -316,23 +316,4 @@ public function getUnrecognizedWords()
     {
         return $this->unrecognizedWords;
     }
-
-    /**
-     * Counts the number of arguments or words.
-     *
-     * @param int $mode The counter mode.
-     *     Either COUNT_NORMAL or COUNT_RECURSIVE.
-     *     When in normal mode, counts the number of arguments.
-     *     When in recursive mode, counts the number of API words.
-     *
-     * @return int The number of arguments/words.
-     */
-    public function count($mode = COUNT_NORMAL)
-    {
-        $result = parent::count($mode);
-        if ($mode !== COUNT_NORMAL) {
-            $result += count($this->unrecognizedWords);
-        }
-        return $result;
-    }
 }

src/PEAR2/Net/RouterOS/ResponseCollection.php

@@ -217,26 +217,13 @@ public function toArray($useIndex = false)
     }
 
     /**
-     * Counts the responses/words in the collection.
-     *
-     * @param int $mode The counter mode.
-     *     Either COUNT_NORMAL or COUNT_RECURSIVE.
-     *     When in normal mode, counts the number of responses.
-     *     When in recursive mode, counts the total number of API words.
+     * Counts the responses in the collection.
      *
      * @return int The number of responses in the collection.
      */
-    public function count($mode = COUNT_NORMAL)
+    public function count()
     {
-        if ($mode !== COUNT_NORMAL) {
-            $result = 0;
-            foreach ($this->responses as $response) {
-                $result += $response->count($mode);
-            }
-            return $result;
-        } else {
-            return count($this->responses);
-        }
+        return count($this->responses);
     }
 
     /**

src/PEAR2/Net/RouterOS/RouterErrorException.php

@@ -0,0 +1,117 @@
+<?php
+
+/**
+ * ~~summary~~
+ *
+ * ~~description~~
+ *
+ * PHP version 5
+ *
+ * @category  Net
+ * @package   PEAR2_Net_RouterOS
+ * @author    Vasil Rangelov <boen.robot@gmail.com>
+ * @copyright 2011 Vasil Rangelov
+ * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @version   GIT: $Id$
+ * @link      http://pear2.php.net/PEAR2_Net_RouterOS
+ */
+/**
+ * The namespace declaration.
+ */
+namespace PEAR2\Net\RouterOS;
+
+/**
+ * Base of this class.
+ */
+use RuntimeException;
+
+/**
+ * Refered to in the constructor.
+ */
+use Exception as E;
+
+/**
+ * Exception thrown by higher level classes (Util, etc.) when the router
+ * returns an error.
+ *
+ * @category Net
+ * @package  PEAR2_Net_RouterOS
+ * @author   Vasil Rangelov <boen.robot@gmail.com>
+ * @license  http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @link     http://pear2.php.net/PEAR2_Net_RouterOS
+ */
+class RouterErrorException extends RuntimeException implements Exception
+{
+    const CODE_ITEM_ERROR           = 0x100000;
+    const CODE_SCRIPT_ERROR         = 0x200000;
+    const CODE_READ_ERROR           = 0x010000;
+    const CODE_WRITE_ERROR          = 0x020000;
+    const CODE_EXEC_ERROR           = 0x040000;
+
+    const CODE_CACHE_ERROR          = 0x100001;
+    const CODE_GET_ERROR            = 0x110001;
+    const CODE_GETALL_ERROR         = 0x110002;
+    const CODE_ADD_ERROR            = 0x120001;
+    const CODE_SET_ERROR            = 0x120002;
+    const CODE_REMOVE_ERROR         = 0x120004;
+    const CODE_SCRIPT_GET_ERROR     = 0x210001;
+    const CODE_SCRIPT_ADD_ERROR     = 0x220001;
+    const CODE_SCRIPT_REMOVE_ERROR  = 0x220004;
+    const CODE_SCRIPT_RUN_ERROR     = 0x240001;
+
+    /**
+     * @var ResponseCollection|null The complete response returned by the router.
+     */
+    private $_responses = null;
+
+    /**
+     * Creates a new RouterErrorException.
+     *
+     * @param string                  $message   The Exception message to throw.
+     * @param int                     $code      The Exception code.
+     * @param E|null                  $previous  The previous exception used for
+     *     the exception chaining.
+     * @param ResponseCollection|null $responses The complete set responses
+     *     returned by the router.
+     */
+    public function __construct(
+        $message,
+        $code = 0,
+        E $previous = null,
+        ResponseCollection $responses = null
+    ) {
+        parent::__construct($message, $code, $previous);
+        $this->_responses = $responses;
+    }
+
+    /**
+     * Gets the complete set responses returned by the router.
+     *
+     * @return ResponseCollection|null The complete set responses
+     *     returned by the router.
+     */
+    public function getResponses()
+    {
+        return $this->_responses;
+    }
+
+    // @codeCoverageIgnoreStart
+    // String representation is not reliable in testing
+
+    /**
+     * Returns a string representation of the exception.
+     *
+     * @return string The exception as a string.
+     */
+    public function __toString()
+    {
+        $result = parent::__toString();
+        if ($this->_responses instanceof ResponseCollection) {
+            $result .= "\nResponse collection:\n" .
+                print_r($this->_responses->toArray(), true);
+        }
+        return $result;
+    }
+
+    // @codeCoverageIgnoreEnd
+}

src/PEAR2/Net/RouterOS/Script.php

@@ -395,7 +395,7 @@ public static function parseValueToArray(
         }
         throw new ParserException(
             'The supplied value can not be converted to an array',
-            ParserException::CODE_DATETIME
+            ParserException::CODE_ARRAY
         );
     }