1 ************************************
2 phancap - website screenshot service
3 ************************************
5 Web service (API) to create website screenshots.
7 Self-hosted and written in PHP. Caching included.
18 #. Download the ``.phar`` file and put it onto your web server
19 #. Open the phar file in your browser
20 #. Click the "setup check" link
21 #. Fix all errors that are reported
22 #. Run ``phancap.phar/get.php?url=cweiske.de`` and see the screenshot
27 With the basic setup, everyone may use your server to create website
29 You may want to change that or simply change some default settings.
31 #. Create a config file ``phancap.phar.config.php``
32 #. Edit it; see the configuration_ options.
38 ``get.php`` supports the following parameters:
45 Browser width (default: 1024)
47 Browser height (default: none)
52 Screenshot width (default: none (no scaling))
54 Screenshot height (default: none)
56 Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
58 Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
60 Maximum age of screenshot in seconds.
61 ISO 8601 duration specifications accepted:
68 The configuration file defines a minimum age that the user cannot undercut
69 (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
71 Authentication parameters
72 =========================
74 Time at which the request URL was generated (unix timestamp)
76 Access token (username)
78 Signature for the request. See the authentication_ section.
84 phancap looks at several places for its configuration file:
86 #. ``phancap.phar.config.php`` in the same directory as your
87 ``phancap.phar`` file.
89 #. ``/etc/phancap.php``
92 Configuration variables
93 =======================
95 Full file system path to image cache directory
97 Full URL to cache directory
99 Credentials for access control
101 ``true`` to allow access to anyone, ``false`` to disable it completely.
102 ``array`` of username - secret key combinations otherwise.
104 Disable ``setup.php`` which will leak file system paths
106 Redirect to static image urls after generating them
108 How long a signature timestamp is considered valid. 2 days default.
109 ``$screenshotMaxAge``
110 Cache time of downloaded screenshots.
112 When the file is as older than this, it gets re-created.
113 ``$screenshotMinAge``
114 Minimum age of a screeshot. 1 hour default.
116 A user cannot set the max age parameter below it.
123 Creating screenshots of websites is a resource intensive process.
124 To prevent unauthorized access to the service, phancap supports authentication
125 via a signature parameter similar to OAuth's ``oauth_signature``.
127 Phancap's configuration file may contain a ``$access`` variable:
130 Everyone is allowed to access the service
132 Nobody is allowed to access the service
134 A list of usernames that are allowed to request screenshots, together
135 with their secret keys (password)::
138 'user1' => 'secret1',
139 'user2' => 'secret2',
142 The signature algorithm is as follows:
144 #. Parameters ``atimestamp`` (current unix timestamp) and
145 ``atoken`` (username) have to be added to the URL parameters
147 #. URL parameters are normalized as described in
148 `OAuth Parameters Normalization`__:
150 #. Sort parameters list by name
151 #. Name and value are `raw-url-encoded`__
152 #. Name and value are concatenated with ``=`` as separator
153 #. The resulting strings are concatenated with ``&`` as separator
155 #. URL parameter string is used together with the secret key
156 to create a `HMAC-SHA1`__ digest
158 #. Digest is appended to the URL as ``asignature``
160 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
161 __ http://tools.ietf.org/html/rfc5849#section-3.6
162 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
170 The ``docs/`` directory contains an example PHP client implementation.
172 We want to create a screenshot of ``http://example.org/`` in size 400x300,
173 using the browser size of 1024x768::
175 http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
177 Phancap's config file contains::
183 Our parameters are thus:
190 ``url`` ``http://example.org/``
195 At first, we need to add parameters ``atimestamp`` and ``atoken``.
196 ``atimestamp`` is the current unix timestamp.
197 ``atoken`` is our user name: ``user``.
199 Now the parameter list is sorted:
204 ``atimestamp`` ``1396353987``
210 ``url`` ``http://example.org/``
213 The parameters are raw-url-encoded. The only value that changes is the url,
214 it becomes ``http%3A%2F%2Fexample.org%2F``.
216 Concatenating the name/value pairs leads to the following string::
218 atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
220 Creating the HMAC digest with sha1, the calculated string and our key
221 ``secret`` gives us the following string::
223 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
225 This is the signature; it gets appended to the URL as ``asignature`` parameter.
231 - `cutycapt <http://cutycapt.sourceforge.net/>`_
232 - imagemagick's ``convert``
234 - PEAR's ``System.php``
240 ``phancap`` is licensed under the `AGPL v3`__ or later.
242 __ http://www.gnu.org/licenses/agpl.html
249 http://cweiske.de/phancap.htm
252 http://git.cweiske.de/phancap.git
254 Mirror: https://github.com/cweiske/phancap
260 Written by Christian Weiske, cweiske@cweiske.de