Added Util::getCurrentTime();

Added pseudo "date" support to Util::parseValue();
Enabled Util::setMenu() to go back to root.

Author: boenrobot

RELEASE-1.0.0b6

@@ -1,7 +1,9 @@
 Bug fixes, mostly.
 
 * New Util methods:
-    - newRequest()
     - comment()
+    - getCurrentTime()
+    - newRequest()
 * Util::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).
-* Client::login() consumes the !done or !fatal response even when called on an already logged in connection.
+* Client::login() consumes the !done or !fatal response even when called on an already logged in connection.
+* Util::setMenu() can now go back to the root menu.

src/PEAR2/Net/RouterOS/Util.php

@@ -30,6 +30,11 @@
  */
 use DateInterval;
 
+/**
+ * Used at {@link Util::getCurrentTime()} to get the proper time.
+ */
+use DateTimeZone;
+
 /**
  * Implemented by this class.
  */
@@ -86,6 +91,10 @@ class Util implements Countable
      * This method is intended to be the very opposite of
      * {@link static::escapeValue()}. That is, results from that method, if
      * given to this method, should produce equivalent results.
+     * 
+     * For better usefulness, in addition to "actual" RouterOS types, a pseudo
+     * "date" type is also recognized, whenever the string is in the form
+     * "M/j/Y".
      *
      * @param string $value The value to be parsed. Must be a literal of a
      *     value, e.g. what {@link static::escapeValue()} will give you.
@@ -97,6 +106,8 @@ class Util implements Countable
      *     - "time" - a {@link DateInterval} object.
      *     - "array" - an array, with the values processed recursively.
      *     - "str" - a string.
+     *     - "date" (pseudo type) - a DateTime object with the specified date,
+     *         at midnight UTC time.
      *     - Unrecognized type - treated as an unquoted string.
      */
     public static function parseValue($value)
@@ -169,20 +180,40 @@ public static function parseValue($value)
                 return new DateInterval(
                     "P{$days}DT{$time[3]}H{$time[4]}M{$secondsSpec}S"
                 );
-            //@codeCoverageIgnoreStart
-            // See previous ignored section's note.
-            // 
-            // This section is added for backwards compatibility with current
-            // PHP versions, when in the future sub-second support is added.
-            // In that event, the test inputs for older versions will be
-            // expected to get a rounded up result of the sub-second data.
+                //@codeCoverageIgnoreStart
+                // See previous ignored section's note.
+                // 
+                // This section is added for backwards compatibility with current
+                // PHP versions, when in the future sub-second support is added.
+                // In that event, the test inputs for older versions will be
+                // expected to get a rounded up result of the sub-second data.
             } catch (E $e) {
                 $secondsSpec = (int)round($secondsSpec);
                 return new DateInterval(
                     "P{$days}DT{$time[3]}H{$time[4]}M{$secondsSpec}S"
                 );
             }
             //@codeCoverageIgnoreEnd
+        } elseif (preg_match(
+            '#^
+                (jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)
+                /
+                (\d\d?)
+                /
+                (\d{4})
+            $#uix',
+            $value,
+            $date
+        )) {
+            try {
+                return DateTime::createFromFormat(
+                    'M/j/Y',
+                    ucfirst($date[1]) . '/' . (int)$date[2] . '/' . $date[3],
+                    new DateTimeZone('UTC')
+                );
+            } catch (E $e) {
+                return $value;
+            }
         } elseif (('"' === $value[0]) && substr(strrev($value), 0, 1) === '"') {
             return str_replace(
                 array('\"', '\\\\', "\\\n", "\\\r\n", "\\\r"),
@@ -500,7 +531,9 @@ public function setMenu($newMenu)
         $newMenu = (string)$newMenu;
         if ('' !== $newMenu) {
             $menuRequest = new Request('/menu');
-            if ('/' === $newMenu[0]) {
+            if ('/' === $newMenu) {
+                $this->menu = '/';
+            } elseif ('/' === $newMenu[0]) {
                 $this->menu = $menuRequest->setCommand($newMenu)->getCommand();
             } else {
                 $this->menu = $menuRequest->setCommand(
@@ -639,6 +672,39 @@ public function clearIdCache()
         return $this;
     }
 
+    /**
+     * Gets the current time on the router.
+     * 
+     * Gets the current time on the router, regardless of the current menu.
+     * 
+     * If your router uses a "manual" timezone, the resulting object will use
+     * the "gmt-offset" as the timezone identifier.
+     * 
+     * @return DateTime The current time of the router, as a DateTime object.
+     */
+    public function getCurrentTime()
+    {
+        $clock = $this->client->sendSync(
+            new Request('/system/clock/print')
+        )->current();
+        $datetime = ucfirst($clock->getProperty('date')) . ' ' .
+            $clock->getProperty('time');
+        if ('manual' === $clock->getProperty('time-zone-name')) {
+            $result = DateTime::createFromFormat(
+                'M/j/Y H:i:s P',
+                $datetime . ' ' . $clock->getProperty('gmt-offset'),
+                new DateTimeZone('UTC')
+            );
+        } else {
+            $result = DateTime::createFromFormat(
+                'M/j/Y H:i:s',
+                $datetime,
+                new DateTimeZone($clock->getProperty('time-zone-name'))
+            );
+        }
+        return $result;
+    }
+
     /**
      * Finds the IDs of items at the current menu.
      *

tests/Util/Safe.php

@@ -29,6 +29,7 @@ abstract class Safe extends PHPUnit_Framework_TestCase
     public function testSetGetMenu()
     {
         $this->assertSame('/', $this->util->getMenu());
+        $this->assertSame('/', $this->util->setMenu('/')->getMenu());
         $this->assertSame(
             '/queue',
             $this->util->setMenu('queue')->getMenu()

tests/Util/Unsafe.php

@@ -261,6 +261,47 @@ public function testSetAndEdit()
 
         $this->util->remove($id);
     }
+    
+    /**
+     * @depends testSetAndEdit
+     */
+    public function testGetCurrentTime()
+    {
+        $originalTimezone = $this->util->setMenu('/system clock')
+            ->get(null, 'time-zone-name');
+        $originalTimezoneAutodetect = $this->util
+            ->get(null, 'time-zone-autodetect');
+        
+        $this->util->set(
+            null,
+            array(
+                'time-zone-autodetect' => 'false',
+                'time-zone-name' => TEST_TIMEZONE
+            )
+        );
+        $curTime = $this->util->setMenu('/')->getCurrentTime();
+        $this->assertInstanceOf(
+            'DateTime',
+             $curTime
+        );
+        $this->assertSame(TEST_TIMEZONE, $curTime->getTimezone()->getName());
+        
+        $this->util->setMenu('/system clock')
+            ->set(null, array('time-zone-name' => 'manual'));
+        $curTimeInManual = $this->util->setMenu('/')->getCurrentTime();
+        $this->assertNotSame(
+            TEST_TIMEZONE,
+            $curTimeInManual->getTimezone()->getName()
+        );
+        
+        $this->util->setMenu('/system clock')->set(
+            null,
+            array(
+                'time-zone-name' => $originalTimezone,
+                'time-zone-autodetect' => $originalTimezoneAutodetect
+            )
+        );
+    }
 
     /**
      * @depends testRemove

tests/phpunit.xml

@@ -117,6 +117,12 @@
         -->
         <const name="TEST_FILE_NAME" value="API_TEST.txt" />
 
+        <!--
+        A name for a test timezone. It should be a name not in use by the
+        router or server, but not necesarily, and must NOT be UTC.
+        -->
+        <const name="TEST_TIMEZONE" value="Europe/Sofia" />
+
     </php>
     <testsuites>
         <testsuite name="All Tests">