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
- Configurable browser size
- Configurable screenshot size
- Clip and full page rendering (full height)
- JPG, PNG and PDF output (PDFs are searchable)
- Can run on a normal web server without GUI. See dependencies.
- Generated images get meta data embedded:
- URL of captured page
- Capture settings
phancap does not rely on a "real" browser.
cutycapt is utilized, which uses a pretty bare webkit to render
Do not expect pixel-for-pixel identical rendering as your desktop browser.
.pharfile 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
phancap.phar/get.php?url=cweiske.deand see the screenshot
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
- Edit it; see the configuration options.
get.php supports the following parameters:
- Website URL
- Browser width (default: 1024)
- Browser height (default: none)
- Screenshot width (default: none (no scaling))
- Screenshot height (default: none)
- Screenshot format (
- Screenshot mode (
page(full website height))
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 (
- Time at which the request URL was generated (unix timestamp)
- Access token (username)
- Signature for the request. See the authentication section.
phancap looks at several places for its configuration file:
phancap.phar.config.phpin the same directory as your
- Full file system path to image cache directory
- Full URL to cache directory
Credentials for access control
trueto allow access to anyone,
falseto disable it completely.
arrayof username - secret key combinations otherwise.
Additional command line parameters for cutycapt. Can be used to e.g. enable browser plugins:
$cutycapt['parameters'] = '--plugins=on';
- Maximal time in seconds to wait for cutycapt to finish rendering. Defaults to 30 seconds.
setup.phpwhich will leak file system paths
- Redirect to static image urls after generating them
- How long a signature timestamp is considered valid. 2 days default.
Cache time of downloaded screenshots.
When the file is as older than this, it gets re-created.
Minimum age of a screeshot. 1 hour default.
A user cannot set the max age parameter below it.
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
Phancap's configuration file may contain a
- Everyone is allowed to access the service
- Nobody is allowed to access the service
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:
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
- The resulting strings are concatenated with
- URL parameter string is used together with the secret key to create a HMAC-SHA1 digest
- Digest is appended to the URL as
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:
Phancap's config file contains:
$access = array( 'user' => 'secret' );
Our parameters are thus:
At first, we need to add parameters
atimestamp is the current unix timestamp.
atoken is our user name:
Now the parameter list is sorted:
The parameters are raw-url-encoded. The only value that changes is the url,
Concatenating the name/value pairs leads to the following string:
Creating the HMAC digest with sha1, the calculated string and our key
secret gives us the following string:
This is the signature; it gets appended to the URL as
- External tools:
- Libraries (already included in the
phancap is licensed under the AGPL v3 or later.
- Web site
- Source code
Written by Christian Weiske, email@example.com
All of those are open source:
- http://code.google.com/p/browsershots/ (python)
- https://github.com/gre/screenshot-webservice (scala)
Releasing a new version
- Change version number in
- Deploy the new files in
- Tag the new version in git