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

• 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

#. Download the .phar file and put it onto your web server
#. 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.
#. Click the "setup check" link
#. Fix all errors that are reported
#. Run phancap.phar/get.php?url=cweiske.de and see the screenshot

__ http://cweiske.de/tagebuch/phar-webserver.htm

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.

#. Create a config file phancap.phar.config.php
#. 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:

#. phancap.phar.config.php in the same directory as your
phancap.phar file.

#. /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:

#. Parameters atimestamp (current unix timestamp) and
atoken (username) have to be added to the URL parameters

#. URL parameters are normalized as described in
OAuth Parameters Normalization__:

#. Sort parameters list by name
#. Name and value are raw-url-encoded__
#. Name and value are concatenated with = as separator
#. The resulting strings are concatenated with & as separator

#. URL parameter string is used together with the secret key
to create a HMAC-SHA1__ digest

#. Digest is appended to the URL as asignature

__ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
__ http://tools.ietf.org/html/rfc5849#section-3.6
__ http://tools.ietf.org/html/rfc5849#section-3.4.2

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 <http://cutycapt.sourceforge.net/>_
  • exiftool <http://owl.phy.queensu.ca/~phil/exiftool/>_
  • imagemagick's <http://www.imagemagick.org/>_ 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.

__ http://www.gnu.org/licenses/agpl.html

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

#. Update ChangeLog
#. Change version number in build.xml
#. Run phing
#. Deploy the new files in dist/
#. Tag the new version in git