1.0.0b6

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 one, and a new $from argument as a second one.
  • All Util CRUD methods throw RouterErrorException when the router returns an error. Previously, you'd need to inspect the returned value to check if there's an error.
  • 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::fileGetContents() now throws RouterErrorException if the file doesn't exist or if there are other problems with getting its contents. Previously, it returned FALSE for such cases.
  • 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').
• New Util methods:
  • comment()
  • getCurrentTime()
  • newRequest()
• Script::escapeString() no longer escapes bytes above 0x7F. This means that parameter string values are now influenced by charset settings, and thus no additional conversion is necessary. A new second argument can be set to TRUE to escape all bytes, including the previously untouched ASCII alphanumeric characters and underscores.
• Stream parameters in Script::append() (and inherently, Script::prepare() and Util::exec()) now have ALL bytes escaped.
• Script::escapeValue() converts NULL to "nil" instead of "nothing".
• The $params array in Script::append() can declare variables with a value of type "nothing" by using numeric keys, and the variable names as values.
• 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::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::exec() and stream valued arguments in both Util and Client no longer cause a hang when using charset conversion.
• 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.
• Client::sendAsync() no longer throws an exception if a request is canceled multiple times by the returned value of a callback.
• The console now checks whether PEAR2_Console_CommandLine is installed, ensuring better error messages when this package is installed without its optional dependencies.

1.0.0b5

Console, some overall improvements, including BREAKING CHANGES.

• The PHAR file is now also a console. When installed, the console is available from the executable "roscon".
• BREAKING CHANGES:
  • Response::getArgument() is renamed to Response::getProperty() (Note: Request::getArgument() is still valid). Response::getArgument() is left issuing an E_USER_DEPRECATED notice, and will be removed in a later release.
  • Message::getAllArguments() is removed in favor of IteratorAggregate implementation that returns an ArrayObject. For most intents and purposes, you should be able to just search&replace "->getAllArguments()" with an empty string (that will implicitly call getIterator()). If you require the arguments as a "real" array, you can replace "->getAllArguments()" with "->getIterator()->getArrayCopy()".
  • Message::__invoke() without arguments is now a shortcut for getTag() instead of getting all arguments.
  • Util::changeMenu() is now renamed to Util::setMenu() and always returns the Util object itself.
  • ResponseCollection::__invoke() without arguments (or NULL) is now a shortcut for getting the iterator of the current response, instead of for seeking to the last response. Replace "()" with "(-1)" or "->end()" to achieve the old effect.
  • ResponseCollection::getLast() is removed. To get the last response, you can instead use array access (or offsetGet()) with "-1" as the offset. Or simply search&replace "->getLast()" with "->offsetGet(-1)".
  • ResponseCollection::getArgumentMap() is renamed to ResponseCollection::getPropertyMap().
  • All Query::ACTION_* constants are renamed to Query::OP_*, and shortened (GREATHER_THAN is now GT, etc.).
• New Util methods:
  • getMenu() (serves the same purpose as previously Util::changeMenu() with an emptry string)
  • getAll()
  • count() (makes Util an implementation of Countable, reports the number of items at the current menu)
  • prepareScript()
  • appendScript()
• Message now implements Countable, reporting the number of arguments (on COUNTER_NORMAL) or words (on COUNT_RECURSIVE).
• Util::get() now uses RouterOS' "get" command, unless it returns an empty !done response (as it does for RouterOS versions prior to 6.0), in which case it automatically fallbacks to a print with a query.
• Util::escapeValue() and Util::parseValue() now support associative arrays (introduced in RouterOS 6.2).
• Util::escapeValue() now correctly converts DateTime objects to DateInterval objects relative to UNIX epoch time in UTC. Previously, the current time zone was used instead of UTC.
• Util::add() and Util::set()/Util::edit() now support flags as values with a numeric key.
• Util::filePutContents() now behaves correctly when the underlying Client has enabled streaming of responses and/or when the contents is in a stream.
• Responses in ResponseCollection can now be getted or seeked to a value relative from the end by supplying a negative offset.
• ResponseCollection can now be searched by argument property values, if you first designate an argument a property name with the new ResponseCollection::setIndex() method.
• ResponseCollection can now produce a sorted response collection based on user defined criteria using the new ResponseCollection::orderBy() method.
• Util::find() now always returns a comma separated list when used without arguments (as opposed to ";" separated, in more recent RouterOS versions).
• Response receiving now resets if an empty sentence is received, instead of throwing an exception.
• New Communicator::seekableStreamLength() method, used internally by Util::filePutContents().
• Doc fixes (Notably: Clarified the acceptability of seekable streams as argument values, which has been present for a long time, but never documented).
• CS fixes.

1.0.0b4

Brand new way of manipulating data, encryption, and listen...

• A new Util class that abstracts away tons of fancy features, including:
  • CRUD operations
  • Support of targeting and finding entries by numbers, just like from terminal
  • Executing scripts (with the ability to pass typed parameters ala SQL prepared statements)
  • Putting and getting files out of RouterOS
  • Helper methods for converting back and forth between PHP and RouterOS values.
• Support for encrypted connections, both with and without a certificate. Note that due to known issues with PHP itself, encrypted connections may be unstable (as in "sometimes disconnect suddenly" or "sometimes hang when you use Client::sendSync() and/or Client::completeRequest() and/or Client::loop() without a timeout").
• Client::loop() and Client::completeRequest() no longer fail if there's no reply within "default_socket_timeout" seconds. This means you can now use the "listen" command without also setting up something else to keep the connection busy.
• Client::loop() now accepts timeouts modeled after stream_select()'s, as opposed to a single float value. As before, the default is "no time limit", but is now specified with NULL instead of 0. Analogous arguments have been added to Response's constructor.
• When receiving, the release lock is released when ANY exception is thrown. Previously, this would be so only in case of SocketException.
• Chnaged the PHAR stub to not fail when reading the hash fails.
• Exceptions now use constants to hold each code.
• Doc and CS fixes, and unit test reorganization.

1.0.0b3

Bug fixes on edge cases, and some API changes

• (GH #6) Persistent connections are now properly supported. Added a new Registry class to facilitate this.
• The second and third argument of Request::__construct() have been swapped.
• At Request::__construct(), a backslash can now be escaped in an argument value, and arguments can be spread across multiple lines.
• Client::getStreamResponses() and Client::setStreamResponses() are now Client::isStreamingResponses() and Client::setStreamingResponses(), respectively.
• Query now uses things statically, allowing extensions in the process.
• ResponseCollection::__invoke() now seeks instead of getting.
• (GH #4) Client::completeRequest() now works with requests that use a callback.
• Client::sendSync() now accepts requests with a tag.
• Added support for non ASCII passwords.
• Client now throws this package's SocketException on connection errors. The originating Transmitter exception is available in the trace.
• Documentation fixes.

1.0.0b2

A lot of new conviniences and a few bug fixes.

• Added __invoke() at Client, Communicator, Message, Request and ResponseCollection.
• Added support for CLI argument syntax at Request constructor.
• Added optional arguments to request constructor for a tag and a query.
• Added Communicator::isSeekableStream() and made Communicator::sendWordFromStream() use it.
• Added ResponseCollection::prev() and ResponseCollection::end().
• Changed the default value of the $value of Message::setArgument from NULL to an empty string.
• Changed ResponseCollection::getLast() to return FALSE when the collection is empty.
• Changed Request::setArgument() so that any invalid value is casted to string.
• Changed Autoload.php to also autoload PEAR2_Net_Transmitter's autoloader if it's not already there.

1.0.0b1

First PEAR2 release