phancap - website screenshot service

Web service (API) to create website screenshots.

Self-hosted and written in PHP. Caching included.

phancap is useful for:

• Show screenshots for websites in your bookmarking application
• Archive a HTML page as PDF for later viewing

Contents

• Features
• Getting started
  • Basic setup
  • Advanced setup
• URL parameters
  • Browser parameters
  • Screenshot parameters
  • Authentication parameters
• Configuration
  • Configuration variables
• Authentication
  • Example
• Dependencies
• About phancap
  • License
  • Homepage
  • Author
• Alternatives
• Development
  • Releasing a new version

Features

• Configurable browser size
• Configurable screenshot size
• Clip and full page rendering (full height)
• JPG, PNG and PDF output (PDFs are searchable)
• Authentication
• Can run on a normal web server without GUI. See dependencies.
• Generated images get meta data embedded:
  • URL of captured page
  • Capture settings

Note

phancap does not rely on a "real" browser. Currently cutycapt is utilized, which uses a pretty bare webkit to render the pages. Do not expect pixel-for-pixel identical rendering as your desktop browser.

Getting started

Basic setup

1. Download the .phar file and put it onto your web server

2. Open the phar file in your browser

   If you only see text beginning with <?php, you need to setup .phar file extension handling in your web server first.

3. Click the "setup check" link

4. Fix all errors that are reported

5. Run phancap.phar/get.php?url=cweiske.de and see the screenshot

Advanced setup

With the basic setup, everyone may use your server to create website screenshots. You may want to change that or simply change some default settings.

1. Create a config file phancap.phar.config.php
2. Edit it; see the configuration options.

URL parameters

get.php supports the following parameters:

Browser parameters

url

Website URL

bwidth

Browser width (default: 1024)

bheight

Browser height (default: none)

Screenshot parameters

swidth

Screenshot width (default: none (no scaling))

sheight

Screenshot height (default: none)

sformat

Screenshot format (png, jpg, pdf, default: png)

smode

Screenshot mode (screen (4:3) or page (full website height))

smaxage

Maximum age of screenshot in seconds. ISO 8601 duration specifications accepted:

• P1Y - 1 year
• P2W - 2 weeks
• P1D - 1 day
• PT4H - 4 hours

The configuration file defines a minimum age that the user cannot undercut ($screenshotMinAge), as well as a default value ($screenshotMaxAge).

Authentication parameters

atimestamp

Time at which the request URL was generated (unix timestamp)

atoken

Access token (username)

asignature

Signature for the request. See the authentication section.

Configuration

phancap looks at several places for its configuration file:

1. phancap.phar.config.php in the same directory as your phancap.phar file.
2. /etc/phancap.php

Configuration variables

$cacheDir

Full file system path to image cache directory

$cacheDirUrl

Full URL to cache directory

$access

Credentials for access control

true to allow access to anyone, false to disable it completely. array of username - secret key combinations otherwise.

$cutycapt['parameters']

Additional command line parameters for cutycapt. Can be used to e.g. enable browser plugins:

$cutycapt['parameters'] = '--plugins=on';

$cutycapt['maxWaitTime']

Maximal time in seconds to wait for cutycapt to finish rendering. Defaults to 30 seconds.

$disableSetup

Disable setup.php which will leak file system paths

$redirect

Redirect to static image urls after generating them

$timestampmaxAge

How long a signature timestamp is considered valid. 2 days default.

$screenshotMaxAge

Cache time of downloaded screenshots.

When the file is as older than this, it gets re-created.

$screenshotMinAge

Minimum age of a screeshot. 1 hour default.

A user cannot set the max age parameter below it.

Authentication

Creating screenshots of websites is a resource intensive process. To prevent unauthorized access to the service, phancap supports authentication via a signature parameter similar to OAuth's oauth_signature.

Phancap's configuration file may contain a $access variable:

true

Everyone is allowed to access the service

false

Nobody is allowed to access the service

array

A list of usernames that are allowed to request screenshots, together with their secret keys (password):

$access = array(
   'user1' => 'secret1',
   'user2' => 'secret2',
)

The signature algorithm is as follows:

1. Parameters atimestamp (current unix timestamp) and atoken (username) have to be added to the URL parameters
2. URL parameters are normalized as described in OAuth Parameters Normalization:
   1. Sort parameters list by name
   2. Name and value are raw-url-encoded
   3. Name and value are concatenated with = as separator
   4. The resulting strings are concatenated with & as separator
3. URL parameter string is used together with the secret key to create a HMAC-SHA1 digest
4. Digest is appended to the URL as asignature

Example

Note

The docs/ directory contains an example PHP client implementation.

We want to create a screenshot of http://example.org/ in size 400x300, using the browser size of 1024x768:

http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768

Phancap's config file contains:

$access = array(
    'user' => 'secret'
);

Our parameters are thus:

Name	Value
swidth	400
sheight	300
url	http://example.org/
bwidth	1024
bheight	768

At first, we need to add parameters atimestamp and atoken. atimestamp is the current unix timestamp. atoken is our user name: user.

Now the parameter list is sorted:

Name	Value
atimestamp	1396353987
atoken	user
bheight	768
bwidth	1024
sheight	300
swidth	400
url	http://example.org/

The parameters are raw-url-encoded. The only value that changes is the url, it becomes http%3A%2F%2Fexample.org%2F.

Concatenating the name/value pairs leads to the following string:

atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F

Creating the HMAC digest with sha1, the calculated string and our key secret gives us the following string:

9a12eac5ff859f9306eaaf5a18b9a931fe10b89d

This is the signature; it gets appended to the URL as asignature parameter.

Dependencies

• External tools:
  • cutycapt
  • exiftool
  • imagemagick's convert
  • xvfb-run
• Libraries (already included in the .phar):
  • PEAR's System.php

About phancap

License

phancap is licensed under the AGPL v3 or later.

Homepage

Web site

http://cweiske.de/phancap.htm

Source code

http://git.cweiske.de/phancap.git

Mirror: https://github.com/cweiske/phancap

Author

Written by Christian Weiske, cweiske@cweiske.de

Alternatives

All of those are open source:

• http://code.google.com/p/browsershots/ (python)
• https://github.com/gre/screenshot-webservice (scala)

Development

Releasing a new version

1. Update ChangeLog
2. Change version number in build.xml
3. Run phing
4. Deploy the new files in dist/
5. Tag the new version in git