README

This is an API wrapper for the Screenshot Machine service. This library is not affiliated with Screenshot Machine in any way.

Requirements

This library requires Yii2 version 2.0.13 or higher. This is because of the new implementation of BaseObject. If you are running an older version of Yii2, it might be time to update the core framework by following the upgrade note here.

Installation

The preferred way to install this extension is through composer.

Either run

composer require --prefer-dist wadeshuler/yii2-screenshotmachine "~1.0"

or add

"wadeshuler/yii2-screenshotmachine": "~1.0"

to the require section of your composer.json file.

Then run composer update.

Configuration

Add the following to your Yii2 config under the components array.

'screenshot' => [
    'class' => 'wadeshuler\screenshotmachine\Screenshot',

    // global config values
    'key' => '',                          // Required: Your unique API key
    //'https' => false,                   // Whether or not to use `https` api url for requests. Default & Free users = false!
    //'generateHash' => false,            // Default: false. Increase security by requiring a hash based on your account's secret
    //'secret' => '',                     // Required if `generateHash` is enabled! Set in your account settings.

    // default values that can be overrode
    //'width' => 500,                     // Default: 120
    //'height' => 500,                    // Default: 90
    //'device' => 'tablet',               // Default: desktop
    //'format' => 'png',                  // Default: jpg
    //'cacheLimit' => 0,                  // Default: 14. Control the Screenshot Machine API's cache time. 0 = disable. max = 14
    //'delay' => 400,                     // Default: 200. Delay in milliseconds to wait after page loads

    // additional options
    //'imageCacheDir' => '@webroot/image-cache', // The image cache directory location. Supports aliases! No trailing slash!
    //'dirMode' => 755,                          // The directory permissions to create dir with if `imageCacheDir` does not exist
    //'filenameTemplate' => '{DEVICE}_{DIMENSION}_{URL}', // The template for generating the filename to save as.
],

The only absolutely required value is your key.

If you set a "secret phrase" in your Screenshot Machine dashboard, then you MUST enter it here as well. It is required if it is set in your account. You will also need to enable generateHash if you have set your secret phrase. The generateHash feature works by making an MD5 hash of the URL and your secret phrase. If your secret phrase is set in your Screenshot Machine dashboard, then ALL requests MUST include the hash. So set generateHash to true and enter in your secret phrase.

If you have a paid Screenshot Machine account, you can use the https feature. Free users can not enable https and will receive an error.

width - An integer between 100 and 1920. Default 120

height - An integer between 100 and 9999, or (string) full for full page. The docs state the "default" height is 90, so this is conflicting. Default: 90

device - There are three possible devices to simulate: desktop, phone, and tablet. Default: desktop

format - There are three possible image formats to save as: jpg, png, gif. Default: jpg

cacheLimit - Apparently, Screenshot Machine uses a cache on their end. The default when not specified, is 14 days. Use 0 if you want to disable their cache. This library will cache images itself, so it does not really matter unless you are deleting and retaking the images yourself. You can use a decimal, ie: 0.041666 for 1 hour.

delay - The amount of time in milliseconds to wait after the page loads before taking the screenshot. This allows you to wait for animations or other things, to snag the perfect shot. Possible values are: 0, 200,400, 600, 800, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000

imageCacheDir - The directory on your Yii2 system where the screenshot images are saved. Aliases are supported. Default: @webroot/image-cache

dirMode - The chmod permissions for the image cache directory creation. The built in Yii2 FileHelper utility is used to create the imageCacheDir if it does not exist. This will use it's default, which is 755.

filenameTemplate - The template to use to generate the filenames. By default, it is {DEVICE}_{DIMENSION}_{URL}. The {URL} value will be MD5 hashed to eliminate any issues with special characters in the file name.

You can also use {WIDTH} and {HEIGHT}. This will give you the same as using dimension: {DEVICE}_{WIDTH}x{HEIGHT}_{URL}

You want to ensure that different types of images will be unique. If you just use {URL} but take both desktop and tablet screenshots, then you will get whichever image was created first (ie: you will get a tablet view instead of desktop)

Usage

Once the extension is installed and configured, you need to use it in your controller. There are 2 main methods, fetch and renderImage.

fetch

This will return an array for use as a JSON API.

Example in your own controller:

    /**
     * Fetch the screenshot image's information, taking a new one if needed.
     *
     * This will provide the image filename and whether it was previously cached.
     *
     * @param $url The url to take a screenshot of
     *
     * @return array The result of the request as a JSON array
     */
    public function actionFetch($url)
    {
        $options = [
            'width'  => Yii::$app->request->get('width', null),
            'height' => Yii::$app->request->get('height', null),
            'device' => Yii::$app->request->get('device', null),
            'format' => Yii::$app->request->get('format', null),
            'cacheLimit' => Yii::$app->request->get('cacheLimit', null),
            'delay' => Yii::$app->request->get('delay', null),
        ];

        $result = Yii::$app->screenshot->fetch($url, $options);
        
        /**
         * $result = [
         *     'response' => true,
         *     'status' => 'success',
         *     'cached' => false,
         *     'data' => $filename
         * ];
         */
        
        return [
            'result' => $result,
        ];
    }

renderImage

This does exactly what it says. It outputs or renders the image. If it was a JPG image, it sets the headers to image/jpeg and displays the image. This allows you to simply reference the image in an HTML image tag, and it will take care of the rest behind the scenes (ie: load cached image or take a screenshot if it is a new URL).

Example use in HTML image tag: <img src="https://api.example.com/v1/image/view?url=https://google.com&width=250&height=250">

In your controller:

    /**
     * View/Render a screenshot image, taking a new one if needed.
     *
     * This will render the image by setting the headers to that matching it (ie: `image/png`) and outputting it.
     *
     * @param $url The url to take a screenshot of
     */
    public function actionView($url)
    {
        $options = [
            'width'  => Yii::$app->request->get('width', null),
            'height' => Yii::$app->request->get('height', null),
            'device' => Yii::$app->request->get('device', null),
            'format' => Yii::$app->request->get('format', null),
            'cacheLimit' => Yii::$app->request->get('cacheLimit', null),
            'delay' => Yii::$app->request->get('delay', null),
        ];

        Yii::$app->screenshot->renderImage($url, $options);
    }

Extra

You can basically set every option, including your key and secret, within the controller. This will override what you have configured in your Yii2 config file. In the above examples, we fetch some options from the request, such as width and height. You DO NOT want to allow the key and others to be set with a GET or POST variable. However, you can add some of your own logic to handle it within your code.

In the example controller you can see multiple use cases, including how to rotate your keys depending on which server the request came from. This allows you to use multiple Screenshot Machine accounts but one central API to act as a middle man or proxy.

Donate

Please consider donating if you find my code useful.

wadeshuler / yii2-screenshotmachine

Maintainers

Details