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.
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.
- Download the .phar file and put it onto your web server
- Open the phar file in your browser
- Click the "setup check" link
- Fix all errors that are reported
- Run phancap.phar/get.php?url=cweiske.de and see the screenshot
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 (png, jpg, pdf, default: png)
- Screenshot mode (screen (4:3) or 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 ($screenshotMaxAge).
phancap looks at several places for its configuration file:
- phancap.phar.config.php in the same directory as your phancap.phar file.
- Full file system path to image cache directory
- Full URL to cache directory
Credentials for access control
true to allow access to anyone, false to disable it completely. array of username - secret key combinations otherwise.
- Disable setup.php which 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 oauth_signature.
Phancap's configuration file may contain a $access variable:
- 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:
- 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
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:
Phancap's config file contains:
$access = array( 'user' => 'secret' );
Our parameters are thus:
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:
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:
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 asignature parameter.