1 ************************************
2 phancap - website screenshot service
3 ************************************
5 Web service to create website screenshots.
7 Self-hosted and written in PHP. Caching included.
13 ``get.php`` supports the following parameters:
20 Browser width (default: 1024)
22 Browser height (default: none)
27 Screenshot width (default: none (no scaling))
29 Screenshot height (default: none)
31 Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
33 Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
35 Maximum age of screenshot in seconds.
36 ISO 8601 duration specifications accepted:
43 The configuration file defines a minimum age that the user cannot undercut
44 (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
46 Authentication parameters
47 =========================
49 Time at which the request URL was generated (unix timestamp)
51 Access token (username)
53 Signature for the request. See the authentication section.
59 Creating screenshots of websites is a resource intensive process.
60 To prevent unauthorized access to the service, phancap supports authentication
61 via a signature parameter similar to OAuth's ``oauth_signature``.
63 Phancap's configuration file may contain a ``$access`` variable:
66 Everyone is allowed to access the service
68 Nobody is allowed to access the service
70 A list of usernames that are allowed to request screenshots, together
71 with their secret keys (password)
73 The signature algorithm is as follows:
75 #. Parameters ``atimestamp`` (current unix timestamp) and
76 ``atoken`` (username) have to be added to the URL parameters
78 #. URL parameters are normalized as described in
79 `OAuth Parameters Normalization`__:
81 #. Sort parameters list by name
82 #. Name and value are `raw-url-encoded`__
83 #. Name and value are concatenated with ``=`` as separator
84 #. The resulting strings are concatenated with ``&`` as separator
86 #. URL parameter string is used together with the secret key
87 to create a `HMAC-SHA1`__ digest
89 #. Digest is appended to the URL as ``asignature``
91 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
92 __ http://tools.ietf.org/html/rfc5849#section-3.6
93 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
101 The ``docs/`` directory contains an example PHP client implementation.
103 We want to create a screenshot of ``http://example.org/`` in size 400x300,
104 using the browser size of 1024x768::
106 http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
108 Phancap's config file contains::
114 Our parameters are thus:
121 ``url`` ``http://example.org/``
126 At first, we need to add parameters ``atimestamp`` and ``atoken``.
127 ``atimestamp`` is the current unix timestamp.
128 ``atoken`` is our user name: ``user``.
130 Now the parameter list is sorted:
135 ``atimestamp`` ``1396353987``
141 ``url`` ``http://example.org/``
144 The parameters are raw-url-encoded. The only value that changes is the url,
145 it becomes ``http%3A%2F%2Fexample.org%2F``.
147 Concatenating the name/value pairs leads to the following string::
149 atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
151 Creating the HMAC digest with sha1, the calculated string and our key
152 ``secret`` gives us the following string::
154 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
156 This is the signature; it gets appended the URL as ``asignature`` parameter.
162 - `cutycapt <http://cutycapt.sourceforge.net/>`_
163 - imagemagick's ``convert``
165 - PEAR's ``System.php``
168 =======================
169 Technical brainstorming
170 =======================
172 Tools to make website screenshots
173 =================================
174 - `cutycapt <http://cutycapt.sourceforge.net/>`_
175 - `khtml2png <http://khtml2png.sourceforge.net/>`_ (outdated)
176 - `phantomjs <http://phantomjs.org/>`_
177 - `python-webkit2png <https://github.com/AdamN/python-webkit2png/>`_
178 - `wkhtmltopdf <http://code.google.com/p/wkhtmltopdf/>`_
185 Page request parameters
186 -----------------------
188 - bwidth (browser width / resolution)
189 - bheight (browser height / resolution)
190 - delay (capture X seconds after page loaded)
191 - useragent (user agent header string)
192 - accepted languages (Accept-Language header)
193 - cookie (set cookie data)
194 - referer (custom referer header)
195 - post data (send POST data as if filled out a form)
197 Screenshot configuration
198 ------------------------
199 - width (of thumbnail)
200 - height (of thumbnail)
201 - output format (jpg, png, pdf)
202 - mode: screen or page (full page height or screen size only)
204 - quality (jpeg image quality)
208 - callback URL (to notify when screenshot is ready)
209 - sync/async (wait for response or just get a 202 accepted)
210 - cache (to force a fresh screenshot with cache=0,
211 otherwise seconds the cache may be old)
213 - token (md5 hash of query string)
215 API parameter sources
216 ---------------------
217 - http://api1.thumbalizr.com/
218 - http://url2png.com/docs/
219 - http://webthumb.bluga.net/apidoc
220 - http://www.page2images.com/Create-website-screenshot-online-API
221 - http://browshot.com/api/documentation
224 Other website screenshot services
225 =================================
226 - http://browsershots.org/
227 - http://browshot.com/
228 - http://ctrlq.org/screenshots/
230 - http://url2png.com/
231 - http://usersnap.com/
232 - http://websnapr.com/
233 - http://webthumb.bluga.net/
234 - http://www.page2images.com/
235 - http://www.shrinktheweb.com/
236 - http://www.thumbalizr.com/
237 - http://www.url2picture.com/
240 Other website screenshot software
241 =================================
242 - https://github.com/microweber/screen