Screenshot clip [ci skip]

Author: gsouf

README.md

@@ -206,7 +206,7 @@ Once the page has completed the navigation you can evaluate arbitrary script on
     // wait for the page to be loaded
     $navigation->waitForNavigation();
 
-    // evaluate script in the browser
+    // take a screenshot
     $screenshot = $page->screenshot([
         'format'  => 'jpeg',  // default to 'png' - possible values: 'png', 'jpeg',
         'quality' => 80       // only if format is 'jpeg' - default 100 
@@ -216,6 +216,36 @@ Once the page has completed the navigation you can evaluate arbitrary script on
     $screenshot->saveToFile('/some/place/file.jpg');
 ```
 
+**choose an area**
+
+You can use the option "clip" in order to choose an area for the screenshot.
+
+```php
+
+    use HeadlessChromium\Clip;
+
+    // navigate
+    $navigation = $page->navigate('http://example.com');
+        
+    // wait for the page to be loaded
+    $navigation->waitForNavigation();
+    
+    // create a rectangle by specifying to left corner coordinates + width and height
+    $x = 10;
+    $y = 10;
+    $width = 100;
+    $height = 100;
+    $clip = new Clip($x, $y, $width, $height);
+    
+    // take the screenshot
+    $screenshot = $page->screenshot([
+        'clip'  => $clip'
+    ]);
+    
+    // save the screenshot
+    $screenshot->saveToFile('/some/place/file.jpg');
+```
+
 
 
 ------------------------------------------------------------------------------------------------------------------------

src/Clip.php

@@ -0,0 +1,115 @@
+<?php
+/**
+ * @license see LICENSE
+ */
+
+namespace HeadlessChromium;
+
+
+class Clip
+{
+
+    protected $x;
+    protected $y;
+    protected $height;
+    protected $width;
+    protected $scale;
+
+    /**
+     * Clip constructor.
+     * @param $x
+     * @param $y
+     * @param $height
+     * @param $width
+     * @param $scale
+     */
+    public function __construct($x, $y, $width, $height, $scale = 1)
+    {
+        $this->x = $x;
+        $this->y = $y;
+        $this->height = $height;
+        $this->width = $width;
+        $this->scale = $scale;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getX()
+    {
+        return $this->x;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getY()
+    {
+        return $this->y;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getHeight()
+    {
+        return $this->height;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getWidth()
+    {
+        return $this->width;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getScale()
+    {
+        return $this->scale;
+    }
+
+    /**
+     * @param mixed $x
+     */
+    public function setX($x)
+    {
+        $this->x = $x;
+    }
+
+    /**
+     * @param mixed $y
+     */
+    public function setY($y)
+    {
+        $this->y = $y;
+    }
+
+    /**
+     * @param mixed $height
+     */
+    public function setHeight($height)
+    {
+        $this->height = $height;
+    }
+
+    /**
+     * @param mixed $width
+     */
+    public function setWidth($width)
+    {
+        $this->width = $width;
+    }
+
+    /**
+     * @param mixed $scale
+     */
+    public function setScale($scale)
+    {
+        $this->scale = $scale;
+    }
+
+}

src/Page.php

@@ -139,6 +139,15 @@ public function hasLifecycleEvent(string $event): bool
 
     /**
      *
+     * Example:
+     *
+     * ```php
+     * $page->screenshot()->saveToFile();
+     * ```
+     *
+     * @param array $options
+     * @return PageScreenshot
+     * @throws CommunicationException
      */
     public function screenshot(array $options = []): PageScreenshot
     {
@@ -185,13 +194,27 @@ public function screenshot(array $options = []): PageScreenshot
             $screenshotOptions['quality'] = $options['quality'];
         }
 
-        // TODO document clip
-        // TODO validate clip/use viewport object
+        // clip
         if (array_key_exists('clip', $options)) {
-            $screenshotOptions['clip'] = $options['clip'];
+
+            // make sure it's a Clip instance
+            if (!($options['clip'] instanceof Clip)) {
+                throw new \InvalidArgumentException(
+                    sprintf('Invalid options "clip" for page screenshot, it must be a %s instance.', Clip::class)
+                );
+            }
+
+            // add to params
+            $screenshotOptions['clip'] = [
+                'x' => $options['clip']->getX(),
+                'y' => $options['clip']->getY(),
+                'width' => $options['clip']->getWidth(),
+                'height' => $options['clip']->getHeight(),
+                'scale' => $options['clip']->getScale()
+            ];
         }
 
-        // request screen shot
+        // request screenshot
         $responseReader = $this->getSession()
             ->sendMessage(new Message('Page.captureScreenshot', $screenshotOptions));
 

src/PageUtils/PageScreenshot.php

@@ -25,6 +25,14 @@ public function __construct(ResponseReader $responseReader)
         $this->responseReader = $responseReader;
     }
 
+    /**
+     * @return ResponseReader
+     */
+    public function getResponseReader(): ResponseReader
+    {
+        return $this->responseReader;
+    }
+
     /**
      * Get base64 representation of the file
      * @return mixed
@@ -49,10 +57,10 @@ public function getBase64()
      * @throws FilesystemException
      * @throws ScreenshotFailed
      */
-    public function saveToFile(string $path)
+    public function saveToFile(string $path, int $timeout = 5000)
     {
 
-        $response = $this->responseReader->waitForResponse();
+        $response = $this->responseReader->waitForResponse($timeout);
 
         if (!$response->isSuccessful()) {
             throw new ScreenshotFailed(