1 ************************************
2 phancap - website screenshot service
3 ************************************
5 Web service (API) to create website screenshots.
7 Self-hosted and written in PHP. Caching included.
10 *phancap* is useful for:
12 - Show screenshots for websites in your bookmarking application
13 - Archive a HTML page as PDF for later viewing
23 * Configurable browser size
24 * Configurable screenshot size
25 * Clip and full page rendering (full height)
26 * JPG, PNG and PDF output (PDFs are searchable)
28 * Can run on a normal web server without GUI. See dependencies_.
32 *phancap* does not rely on a "real" browser.
33 Currently ``cutycapt`` is utilized, which uses a pretty bare webkit to render
35 Do not expect pixel-for-pixel identical rendering as your desktop browser.
44 #. Download the ``.phar`` file and put it onto your web server
45 #. Open the phar file in your browser
47 If you only see text beginning with ``<?php``, you need to
48 `setup .phar file extension handling`__ in your web server first.
49 #. Click the "setup check" link
50 #. Fix all errors that are reported
51 #. Run ``phancap.phar/get.php?url=cweiske.de`` and see the screenshot
53 __ http://cweiske.de/tagebuch/phar-webserver.htm
58 With the basic setup, everyone may use your server to create website
60 You may want to change that or simply change some default settings.
62 #. Create a config file ``phancap.phar.config.php``
63 #. Edit it; see the configuration_ options.
69 ``get.php`` supports the following parameters:
76 Browser width (default: 1024)
78 Browser height (default: none)
83 Screenshot width (default: none (no scaling))
85 Screenshot height (default: none)
87 Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
89 Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
91 Maximum age of screenshot in seconds.
92 ISO 8601 duration specifications accepted:
99 The configuration file defines a minimum age that the user cannot undercut
100 (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
102 Authentication parameters
103 =========================
105 Time at which the request URL was generated (unix timestamp)
107 Access token (username)
109 Signature for the request. See the authentication_ section.
115 phancap looks at several places for its configuration file:
117 #. ``phancap.phar.config.php`` in the same directory as your
118 ``phancap.phar`` file.
120 #. ``/etc/phancap.php``
123 Configuration variables
124 =======================
126 Full file system path to image cache directory
128 Full URL to cache directory
130 Credentials for access control
132 ``true`` to allow access to anyone, ``false`` to disable it completely.
133 ``array`` of username - secret key combinations otherwise.
134 ``$cutycapt['parameters']``
135 Additional command line parameters for cutycapt.
136 Can be used to e.g. enable browser plugins:
138 ``$cutycapt['parameters'] = '--plugins=on';``
139 ``$cutycapt['maxWaitTime']``
140 Maximal time in seconds to wait for cutycapt to finish rendering.
141 Defaults to 30 seconds.
143 Disable ``setup.php`` which will leak file system paths
145 Redirect to static image urls after generating them
147 How long a signature timestamp is considered valid. 2 days default.
148 ``$screenshotMaxAge``
149 Cache time of downloaded screenshots.
151 When the file is as older than this, it gets re-created.
152 ``$screenshotMinAge``
153 Minimum age of a screeshot. 1 hour default.
155 A user cannot set the max age parameter below it.
162 Creating screenshots of websites is a resource intensive process.
163 To prevent unauthorized access to the service, phancap supports authentication
164 via a signature parameter similar to OAuth's ``oauth_signature``.
166 Phancap's configuration file may contain a ``$access`` variable:
169 Everyone is allowed to access the service
171 Nobody is allowed to access the service
173 A list of usernames that are allowed to request screenshots, together
174 with their secret keys (password)::
177 'user1' => 'secret1',
178 'user2' => 'secret2',
181 The signature algorithm is as follows:
183 #. Parameters ``atimestamp`` (current unix timestamp) and
184 ``atoken`` (username) have to be added to the URL parameters
186 #. URL parameters are normalized as described in
187 `OAuth Parameters Normalization`__:
189 #. Sort parameters list by name
190 #. Name and value are `raw-url-encoded`__
191 #. Name and value are concatenated with ``=`` as separator
192 #. The resulting strings are concatenated with ``&`` as separator
194 #. URL parameter string is used together with the secret key
195 to create a `HMAC-SHA1`__ digest
197 #. Digest is appended to the URL as ``asignature``
199 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
200 __ http://tools.ietf.org/html/rfc5849#section-3.6
201 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
209 The ``docs/`` directory contains an example PHP client implementation.
211 We want to create a screenshot of ``http://example.org/`` in size 400x300,
212 using the browser size of 1024x768::
214 http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
216 Phancap's config file contains::
222 Our parameters are thus:
229 ``url`` ``http://example.org/``
234 At first, we need to add parameters ``atimestamp`` and ``atoken``.
235 ``atimestamp`` is the current unix timestamp.
236 ``atoken`` is our user name: ``user``.
238 Now the parameter list is sorted:
243 ``atimestamp`` ``1396353987``
249 ``url`` ``http://example.org/``
252 The parameters are raw-url-encoded. The only value that changes is the url,
253 it becomes ``http%3A%2F%2Fexample.org%2F``.
255 Concatenating the name/value pairs leads to the following string::
257 atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
259 Creating the HMAC digest with sha1, the calculated string and our key
260 ``secret`` gives us the following string::
262 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
264 This is the signature; it gets appended to the URL as ``asignature`` parameter.
272 - `cutycapt <http://cutycapt.sourceforge.net/>`_
273 - `imagemagick's <http://www.imagemagick.org/>`_ ``convert``
276 - Libraries (already included in the ``.phar``):
278 - PEAR's ``System.php``
287 ``phancap`` is licensed under the `AGPL v3`__ or later.
289 __ http://www.gnu.org/licenses/agpl.html
295 http://cweiske.de/phancap.htm
298 http://git.cweiske.de/phancap.git
300 Mirror: https://github.com/cweiske/phancap
305 Written by Christian Weiske, cweiske@cweiske.de
311 All of those are open source:
313 * http://code.google.com/p/browsershots/ (python)
314 * https://github.com/gre/screenshot-webservice (scala)
321 Releasing a new version
322 =======================
324 #. Update ``ChangeLog``
325 #. Change version number in ``build.xml``
327 #. Deploy the new files in ``dist/``
328 #. Tag the new version in git