Added Util::prepareScript() and made Util::exec() use it;

Added the ability of Util::add() and Util::set()/Util::edit() to accept flags as array values with a numeric key;
Util::filePutContents() with NULL as data now causes the removal of a file with that name (+ verification of successful deletion) - it previously caused an error;
Adjusted the methods of ResponseCollection that return a new collection to use "new static" instead of "new ResponseCollection", allowing potential extensions of ResponseCollection;
Fixed Communicator::verifyLengthSupport() - it's 0xFFFFFFFF (8 "F"s), not 0xFFFFFFF (7 "F"s);
Doc fixes.

Author: boenrobot

src/PEAR2/Net/RouterOS/Client.php

@@ -341,7 +341,7 @@ public function getCharset($charsetType)
      *     one last time after that with a response that notifies about the
      *     canceling.
      * 
-     * @return self|Client The client object.
+     * @return $this The client object.
      * @see completeRequest()
      * @see loop()
      * @see cancelRequest()

src/PEAR2/Net/RouterOS/Communicator.php

@@ -391,7 +391,7 @@ public function sendWord($word)
      * supplied stream must be seekable.
      * 
      * @param string   $prefix A string to prepend before the stream contents.
-     * @param resource $stream The stream to send.
+     * @param resource $stream The seekable stream to send.
      * 
      * @return int The number of bytes sent.
      * @see sendWord()
@@ -441,7 +441,7 @@ public function sendWordFromStream($prefix, $stream)
      * 
      * Verifies if the specified length is supported by the API. Throws a
      * {@link LengthException} if that's not the case. Currently, RouterOS
-     * supports words up to 0xFFFFFFF in length, so that's the only check
+     * supports words up to 0xFFFFFFFF in length, so that's the only check
      * performed.
      * 
      * @param int $length The length to verify.
@@ -450,9 +450,9 @@ public function sendWordFromStream($prefix, $stream)
      */
     protected static function verifyLengthSupport($length)
     {
-        if ($length > 0xFFFFFFF) {
+        if ($length > 0xFFFFFFFF) {
             throw new LengthException(
-                'Words with length above 0xFFFFFFF are not supported.',
+                'Words with length above 0xFFFFFFFF are not supported.',
                 LengthException::CODE_UNSUPPORTED,
                 null,
                 $length

src/PEAR2/Net/RouterOS/Message.php

@@ -163,9 +163,15 @@ public function getAllArguments()
     /**
      * Sets an argument for the message.
      * 
-     * @param string $name  Name of the argument.
-     * @param string $value Value of the argument. Setting the value to NULL
-     *     removes an argument of this name.
+     * @param string               $name  Name of the argument.
+     * @param string|resource|null $value Value of the argument as a string or
+     *     seekable stream.
+     *     Setting the value to NULL removes an argument of this name.
+     *     If a seekable stream is provided, it is sent from its current
+     *     posistion to its end, and the pointer is seeked back to its current
+     *     position after sending.
+     *     Non seekable streams, as well as all other types, are casted to a
+     *     string.
      * 
      * @return self|Message The message object.
      * @see getArgument()

src/PEAR2/Net/RouterOS/Query.php

@@ -114,7 +114,7 @@ protected static function sanitizeAction($action)
      * @param string $action One of the ACTION_* constants. Describes the
      *     operation to perform.
      * 
-     * @return self|Query The query object.
+     * @return static The query object.
      */
     public static function where(
         $name,
@@ -128,7 +128,7 @@ public static function where(
     /**
      * Negates the query.
      * 
-     * @return self|Query The query object.
+     * @return $this The query object.
      */
     public function not()
     {
@@ -139,13 +139,18 @@ public function not()
     /**
      * Adds a condition as an alternative to the query.
      * 
-     * @param string $name   The name of the property to test.
-     * @param string $value  The value to test against. Not required for
-     *     existence tests.
-     * @param string $action One of the ACTION_* constants. Describes the
-     *     operation to perform.
+     * @param string               $name   The name of the property to test.
+     * @param string|resource|null $value  Value of the property as a string or
+     *     seekable stream. Not required for existence tests.
+     *     If a seekable stream is provided, it is sent from its current
+     *     posistion to its end, and the pointer is seeked back to its current
+     *     position after sending.
+     *     Non seekable streams, as well as all other types, are casted to a
+     *     string.
+     * @param string               $action One of the ACTION_* constants.
+     *     Describes the operation to perform.
      * 
-     * @return self|Query The query object.
+     * @return $this The query object.
      */
     public function orWhere($name, $value = null, $action = self::ACTION_EXIST)
     {
@@ -156,13 +161,18 @@ public function orWhere($name, $value = null, $action = self::ACTION_EXIST)
     /**
      * Adds a condition in addition to the query.
      * 
-     * @param string $name   The name of the property to test.
-     * @param string $value  The value to test against. Not required for
-     *     existence tests.
-     * @param string $action One of the ACTION_* constants. Describes the
-     *     operation to perform.
+     * @param string               $name   The name of the property to test.
+     * @param string|resource|null $value  Value of the property as a string or
+     *     seekable stream. Not required for existence tests.
+     *     If a seekable stream is provided, it is sent from its current
+     *     posistion to its end, and the pointer is seeked back to its current
+     *     position after sending.
+     *     Non seekable streams, as well as all other types, are casted to a
+     *     string.
+     * @param string               $action One of the ACTION_* constants.
+     *     Describes the operation to perform.
      * 
-     * @return self|Query The query object.
+     * @return $this The query object.
      */
     public function andWhere($name, $value = null, $action = self::ACTION_EXIST)
     {
@@ -227,13 +237,18 @@ private function _send(Communicator $com)
     /**
      * Adds a condition.
      * 
-     * @param string $name   The name of the property to test.
-     * @param string $value  The value to test against. Not required for
-     *     existence tests.
-     * @param string $action One of the ACTION_* constants. Describes the
-     *     operation to perform.
+     * @param string               $name   The name of the property to test.
+     * @param string|resource|null $value  Value of the property as a string or
+     *     seekable stream. Not required for existence tests.
+     *     If a seekable stream is provided, it is sent from its current
+     *     posistion to its end, and the pointer is seeked back to its current
+     *     position after sending.
+     *     Non seekable streams, as well as all other types, are casted to a
+     *     string.
+     * @param string               $action One of the ACTION_* constants.
+     *     Describes the operation to perform.
      * 
-     * @return self|Query The query object.
+     * @return $this The query object.
      */
     protected function addWhere($name, $value, $action)
     {

src/PEAR2/Net/RouterOS/Request.php

@@ -114,7 +114,7 @@ public function __invoke($arg = null)
      * 
      * @param string $command The command to send.
      * 
-     * @return self|Request The request object.
+     * @return $this The request object.
      * @see getCommand()
      * @see setArgument()
      */
@@ -177,7 +177,7 @@ public function getCommand()
      * @param Query $query The query to be set. Setting NULL will remove the
      *     currently associated query.
      * 
-     * @return self|Request The request object.
+     * @return $this The request object.
      * @see getQuery()
      */
     public function setQuery(Query $query = null)
@@ -205,7 +205,7 @@ public function getQuery()
      * 
      * @param string $tag The tag to set.
      * 
-     * @return self|Request The request object.
+     * @return $this The request object.
      * @see getTag()
      */
     public function setTag($tag)
@@ -216,11 +216,17 @@ public function setTag($tag)
     /**
      * Sets an argument for the request.
      * 
-     * @param string $name  Name of the argument.
-     * @param string $value Value of the argument. Setting the value to NULL
-     *     removes an argument of this name.
+     * @param string               $name  Name of the argument.
+     * @param string|resource|null $value Value of the argument as a string or
+     *     seekable stream.
+     *     Setting the value to NULL removes an argument of this name.
+     *     If a seekable stream is provided, it is sent from its current
+     *     posistion to its end, and the pointer is seeked back to its current
+     *     position after sending.
+     *     Non seekable streams, as well as all other types, are casted to a
+     *     string.
      * 
-     * @return self|Request The request object.
+     * @return $this The request object.
      * @see getArgument()
      */
     public function setArgument($name, $value = '')
@@ -231,7 +237,7 @@ public function setArgument($name, $value = '')
     /**
      * Removes all arguments from the request.
      * 
-     * @return self|Request The request object.
+     * @return $this The request object.
      */
     public function removeAllArguments()
     {

src/PEAR2/Net/RouterOS/ResponseCollection.php

@@ -311,7 +311,7 @@ public function getArgumentMap()
      * @param string $type The response type to filter by. Valid values are the
      *     Response::TYPE_* constants.
      * 
-     * @return ResponseCollection A new collection with responses of the
+     * @return static A new collection with responses of the
      *     specified type.
      */
     public function getAllOfType($type)
@@ -320,15 +320,15 @@ public function getAllOfType($type)
         foreach (array_keys($this->responseTypes, $type, true) as $index) {
             $result[] = $this->responses[$index];
         }
-        return new ResponseCollection($result);
+        return new static($result);
     }
 
     /**
      * Gets all responses with a specified tag.
      * 
      * @param string $tag The tag to filter by.
      * 
-     * @return ResponseCollection A new collection with responses having the
+     * @return static A new collection with responses having the
      *     specified tag.
      */
     public function getAllTagged($tag)
@@ -337,7 +337,7 @@ public function getAllTagged($tag)
         foreach (array_keys($this->responseTags, $tag, true) as $index) {
             $result[] = $this->responses[$index];
         }
-        return new ResponseCollection($result);
+        return new static($result);
     }
 
     /**