Add getWindowHandle and newWindow wrappers, plus other cleanup

lib/WebDriver/Alert.php

@@ -16,10 +16,10 @@
  *
  * @package WebDriver
  *
- * @method array accept() Accept Alert
- * @method array dismiss() Dismiss Alert
- * @method array getText() Get Alert Text
- * @method array postText() Send Alert Text
+ * @method array accept() Accept alert.
+ * @method array dismiss() Dismiss alert.
+ * @method array getText() Get alert text.
+ * @method array postText() Send alert text.
  */
 class Alert extends AbstractWebDriver
 {

lib/WebDriver/Container.php

@@ -32,8 +32,8 @@ public function __construct($url)
     {
         parent::__construct($url);
 
-        $locatorStrategy = new \ReflectionClass('WebDriver\LocatorStrategy');
-        $this->strategies  = $locatorStrategy->getConstants();
+        $locatorStrategy  = new \ReflectionClass('WebDriver\LocatorStrategy');
+        $this->strategies = $locatorStrategy->getConstants();
     }
 
     /**

lib/WebDriver/Element.php

@@ -26,9 +26,10 @@
  * @method array location() Determine an element's location on the page.
  * @method array location_in_view() Determine an element's location on the screen once it has been scrolled into view.
  * @method string name() Query for an element's tag name.
- * @method array property($propertyName) Get Element Property
- * @method array rect() Get Element Rect
- * @method array screenshot() Take Element Screenshot
+ * @method array property($propertyName) Get element property.
+ * @method array rect() Get element rect.
+ * @method array screenshot() Take element screenshot.
+ * @method array selected() Is element selected?
  * @method array size() Determine an element's size in pixels.
  * @method void submit() Submit a FORM element.
  * @method string text() Returns the visible text for the element.
@@ -65,7 +66,7 @@ protected function methods()
             'value' => array('POST'),
 
             // Legacy JSON Wire Protocol
-            'displayed' => array('GET'),
+            'displayed' => array('GET'),        // @see https://w3c.github.io/webdriver/#element-displayedness
             'equals' => array('GET'),
             'location' => array('GET'),
             'location_in_view' => array('GET'),

lib/WebDriver/LegacyElement.php

@@ -26,9 +26,9 @@
  * @method array location() Determine an element's location on the page.
  * @method array location_in_view() Determine an element's location on the screen once it has been scrolled into view.
  * @method string name() Query for an element's tag name.
- * @method array property($propertyName) Get Element Property
- * @method array rect() Get Element Rect
- * @method array screenshot() Take Element Screenshot
+ * @method array property($propertyName) Get element property.
+ * @method array rect() Get element rect.
+ * @method array screenshot() Take element screenshot.
  * @method array size() Determine an element's size in pixels.
  * @method void submit() Submit a FORM element.
  * @method string text() Returns the visible text for the element.

lib/WebDriver/LegacyWindow.php

@@ -25,8 +25,6 @@
 class LegacyWindow extends AbstractWebDriver
 {
     /**
-     * Window handle
-     *
      * @var string
      */
     private $windowHandle;
@@ -55,25 +53,33 @@ protected function obsoleteMethods()
     }
 
     /**
-     * Get window handle
+     * Constructor
      *
-     * @return string
+     * @param string      $url
+     * @param string|null $windowHandle
      */
-    public function getHandle()
+    public function __construct($url, $windowHandle = null)
     {
-        return $this->windowHandle;
+        parent::__construct($url);
+
+        $this->windowHandle = $windowHandle;
     }
 
     /**
-     * Constructor
+     * Get window handle: /session/:sessionId/window_handle (GET)
+     * - $session->window($handle)->getHandle()
+     * - $session->window()->getHandle()
      *
-     * @param string $url          URL
-     * @param string $windowHandle Window handle
+     * @return string
      */
-    public function __construct($url, $windowHandle)
+    public function getHandle()
     {
-        $this->windowHandle = $windowHandle;
+        if (! $this->windowHandle) {
+            $result = $this->curl('GET', '_handle');
+
+            $this->windowHandle = $result['value'];
+        }
 
-        parent::__construct($url . '/' . $windowHandle);
+        return $this->windowHandle;
     }
 }

lib/WebDriver/Session.php

@@ -17,8 +17,8 @@
  * @package WebDriver
  *
  * @method void accept_alert() Accepts the currently displayed alert dialog.
- * @method array deleteActions() Release Actions
- * @method array postActions() Perform Actions
+ * @method array deleteActions() Release actions.
+ * @method array postActions() Perform actions.
  * @method string getAlert_text() Gets the text of the currently displayed JavaScript alert(), confirm(), or prompt() dialog.
  * @method void postAlert_text($jsonText) Sends keystrokes to a JavaScript prompt() dialog.
  * @method void back() Navigates backward in the browser history, if possible.
@@ -40,13 +40,13 @@
  * @method void moveto($jsonCoordinates) Move the mouse by an offset of the specified element (or current mouse cursor).
  * @method string getOrientation() Get the current browser orientation.
  * @method void postOrientation($jsonOrientation) Set the current browser orientation.
- * @method array print() Print Page
+ * @method array print() Print page.
  * @method void refresh() Refresh the current page.
  * @method string screenshot() Take a screenshot of the current page.
  * @method string source() Get the current page source.
  * @method string title() Get the current page title.
- * @method string url() Retrieve the URL of the current page
- * @method void postUrl($jsonUrl) Navigate to a new URL
+ * @method string url() Retrieve the URL of the current page.
+ * @method void postUrl($jsonUrl) Navigate to a new URL.
  * @method string window_handle() Retrieve the current window handle.
  * @method array window_handles() Retrieve the list of all window handles available to the session.
  */
@@ -96,7 +96,7 @@ protected function methods()
             'location' => array('GET', 'POST'),
             'moveto' => array('POST'),
             'orientation' => array('GET', 'POST'),
-            'window_handle' => array('GET'),
+            'window_handle' => array('GET'), // see also getWindowHandle()
             'window_handles' => array('GET'),
         );
     }
@@ -218,55 +218,67 @@ public function deleteCookie($cookieName)
     }
 
     /**
-     * Window method chaining, e.g.,
-     * - $session->window($handle)->method() - chaining
+     * Get window handle: /session/:sessionId/window (GET)
+     *                  : /session/:sessionId/window_handle (GET)
+     * - $session->getWindowHandle()
      *
-     * @return \WebDriver\Window
+     * An alternative to $session->window()->getHandle()
+     *
+     * @return mixed
      */
-    public function window()
+    public function getWindowHandle()
     {
-        // legacy window methods
-        if ($this->legacy) {
-            return call_user_func_array(array($this, 'legacyWindow'), func_get_args());
-        }
+        $result = $this->curl('GET', $this->legacy ? '/window_handle' : '/window');
 
-        return new Window($this->url . '/window');
+        return $result['value'];
     }
 
     /**
-     * Legacy window methods: /session/:sessionId/window (POST, DELETE)
-     * - $session->legacyWindow() - close current window
-     * - $session->legacyWindow($name) - set focus
-     * - $session->legacyWindow($window_handle)->method() - chaining
+     * New window: /session/:sessionId/window/new (POST)
+     * - $session->newWindow($type)
      *
-     * @deprecated
+     * @internal "new" is a reserved keyword in PHP, so $session->window()->new() isn't possible
      *
-     * @return \WebDriver\LegacyWindow|\WebDriver\Session
+     * @return \WebDriver\Window
      */
-    public function legacyWindow()
+    public function newWindow($type)
     {
-        // close current window
-        if (func_num_args() === 0) {
-            $this->curl('DELETE', '/window');
+        $arg = func_get_arg(0); // json
 
-            return $this;
-        }
+        $result = $this->curl('POST', '/window/new', $arg);
+
+        return $result['value'];
+    }
+
+    /**
+     * window method chaining: /session/:sessionId/window (POST
+     * - $session->window($jsonHandle) - set focus
+     * - $session->window($handle)->method() - chaining
+     * - $session->window()->method() - chaining
+     *
+     * @return \WebDriver\Session|\WebDriver\Window|\WebDriver\LegacyWindow
+     */
+    public function window()
+    {
+        $arg = null;
 
-        // set focus
-        $arg = func_get_arg(0); // window handle or name attribute
+        // set window focus / switch to window
+        if (func_num_args() === 1) {
+            $arg = func_get_arg(0); // window handle or name attribute
 
-        if (is_array($arg)) {
-            $this->curl('POST', '/window', $arg);
+            if (is_array($arg)) {
+                $this->curl('POST', '/window', $arg);
 
-            return $this;
+                return $this;
+            }
         }
 
-        // chaining
-        return new LegacyWindow($this->url . '/window', $arg);
+        // chaining (with optional handle in $arg)
+        return $this->legacy ? new LegacyWindow($this->url . '/window', $arg) : new Window($this->url . '/window', $arg);
     }
 
     /**
-     * Delete window: /session/:sessionId/window (DELETE)
+     * Close window: /session/:sessionId/window (DELETE)
      *
      * @return \WebDriver\Session
      */

lib/WebDriver/Window.php

@@ -16,21 +16,26 @@
  *
  * @package WebDriver
  *
- * @method array handles() Get Window Handles
- * @method array fullscreen() Fullscreen Window
+ * @method array handles() Get window handles.
+ * @method array fullscreen() Fullscreen window.
  * @method array maximize() Maximize the window if not already maximized.
- * @method array minimize() Minimize Window
+ * @method array minimize() Minimize window.
  * @method array getPosition() Get position of the window.
  * @method void postPosition($json) Change position of the window.
- * @method array getRect() Get Window Rect
- * @method array postRect() Set Window Rect
- * @method array getSize() Get Window Size
- * @method array postSize() Set Window Size
+ * @method array getRect() Get window rect.
+ * @method array postRect() Set window rect.
+ * @method array getSize() Get window size.
+ * @method array postSize() Set window size.
  */
 class Window extends AbstractWebDriver
 {
     const WEB_WINDOW_ID = 'window-fcc6-11e5-b4f8-330a88ab9d7f';
 
+    /**
+     * @var string
+     */
+    private $windowHandle;
+
     /**
      * {@inheritdoc}
      */
@@ -40,42 +45,43 @@ protected function methods()
             'handles' => array('GET'),
             'fullscreen' => array('POST'),
             'maximize' => array('POST'),
-            'position' => array('GET', 'POST'),
-            'size' => array('GET', 'POST'),
-
-            // obsolete
             'minimize' => array('POST'),
+            'position' => array('GET', 'POST'),
             'rect' => array('GET', 'POST'),
+            'size' => array('GET', 'POST'),
         );
     }
 
     /**
-     * Get window handle
+     * Constructor
      *
-     * @return string
+     * @param string      $url
+     * @param string|null $windowHandle
      */
-    public function getHandle()
+    public function __construct($url, $windowHandle = null)
     {
-        $result = $this->curl('GET', $this->url);
+        parent::__construct($url);
 
-        return array_key_exists(self::WEB_WINDOW_ID, $result['value'])
-            ? $result['value'][self::WEB_WINDOW_ID]
-            : $result['value'];
+        $this->windowHandle = $windowHandle;
     }
 
     /**
-     * New window: /session/:sessionId/window/new (POST)
-     *
-     * @deprecated
-     *
-     * @param string $name
+     * Get window handle: /session/:sessionId/window (GET)
+     * - $session->window($handle)->getHandle()
+     * - $session->window()->getHandle()
      *
-     * @return \WebDriver\Window
+     * @return string
      */
-    public function focusWindow($name)
+    public function getHandle()
     {
-        $this->curl('POST', '/new');
+        if (! $this->windowHandle) {
+            $result = $this->curl('GET', $this->url);
+
+            $this->windowHandle = array_key_exists(self::WEB_WINDOW_ID, $result['value'])
+                ? $result['value'][self::WEB_WINDOW_ID]
+                : $result['value'];
+        }
 
-        return $this;
+        return $this->windowHandle;
     }
 }