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 Authentication parameters
36 =========================
38 Time at which the request URL was generated (unix timestamp)
40 Access token (username)
42 Signature for the request. See the authentication section.
48 Creating screenshots of websites is a resource intensive process.
49 To prevent unauthorized access to the service, phancap supports authentication
50 via a signature parameter similar to OAuth's ``oauth_signature``.
52 Phancap's configuration file may contain a ``$access`` variable:
55 Everyone is allowed to access the service
57 Nobody is allowed to access the service
59 A list of usernames that are allowed to request screenshots, together
60 with their secret keys (password)
62 The signature algorithm is as follows:
64 #. Parameters ``atimestamp`` (current unix timestamp) and
65 ``atoken`` (username) have to be added to the URL parameters
67 #. URL parameters are normalized as described in
68 `OAuth Parameters Normalization`__:
70 #. Sort parameters list by name
71 #. Name and value are `raw-url-encoded`__
72 #. Name and value are concatenated with ``=`` as separator
73 #. The resulting strings are concatenated with ``&`` as separator
75 #. URL parameter string is used together with the secret key
76 to create a `HMAC-SHA1`__ digest
78 #. Digest is appended to the URL as ``asignature``
80 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
81 __ http://tools.ietf.org/html/rfc5849#section-3.6
82 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
87 We want to create a screenshot of ``http://example.org/`` in size 400x300,
88 using the browser size of 1024x768::
90 http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
92 Phancap's config file contains::
98 Our parameters are thus:
105 ``url`` ``http://example.org/``
110 At first, we need to add parameters ``atimestamp`` and ``atoken``.
111 ``atimestamp`` is the current unix timestamp.
112 ``atoken`` is our user name: ``user``.
114 Now the parameter list is sorted:
119 ``atimestamp`` ``1396353987``
125 ``url`` ``http://example.org/``
128 The parameters are raw-url-encoded. The only value that changes is the url,
129 it becomes ``http%3A%2F%2Fexample.org%2F``.
131 Concatenating the name/value pairs leads to the following string::
133 atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
135 Creating the HMAC digest with sha1, the calculated string and our key
136 ``secret`` gives us the following string::
138 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
140 This is the signature; it gets appended the URL as ``asignature`` parameter.
146 - `cutycapt <http://cutycapt.sourceforge.net/>`_
147 - imagemagick's ``convert``
152 =======================
153 Technical brainstorming
154 =======================
156 Tools to make website screenshots
157 =================================
158 - `cutycapt <http://cutycapt.sourceforge.net/>`_
159 - `khtml2png <http://khtml2png.sourceforge.net/>`_ (outdated)
160 - `phantomjs <http://phantomjs.org/>`_
161 - `python-webkit2png <https://github.com/AdamN/python-webkit2png/>`_
162 - `wkhtmltopdf <http://code.google.com/p/wkhtmltopdf/>`_
169 Page request parameters
170 -----------------------
172 - bwidth (browser width / resolution)
173 - bheight (browser height / resolution)
174 - delay (capture X seconds after page loaded)
175 - useragent (user agent header string)
176 - accepted languages (Accept-Language header)
177 - cookie (set cookie data)
178 - referer (custom referer header)
179 - post data (send POST data as if filled out a form)
181 Screenshot configuration
182 ------------------------
183 - width (of thumbnail)
184 - height (of thumbnail)
185 - output format (jpg, png, pdf)
186 - mode: screen or page (full page height or screen size only)
188 - quality (jpeg image quality)
192 - callback URL (to notify when screenshot is ready)
193 - sync/async (wait for response or just get a 202 accepted)
194 - cache (to force a fresh screenshot with cache=0,
195 otherwise seconds the cache may be old)
197 - token (md5 hash of query string)
199 API parameter sources
200 ---------------------
201 - http://api1.thumbalizr.com/
202 - http://url2png.com/docs/
203 - http://webthumb.bluga.net/apidoc
204 - http://www.page2images.com/Create-website-screenshot-online-API
205 - http://browshot.com/api/documentation
208 Other website screenshot services
209 =================================
210 - http://browsershots.org/
211 - http://browshot.com/
212 - http://ctrlq.org/screenshots/
214 - http://url2png.com/
215 - http://usersnap.com/
216 - http://websnapr.com/
217 - http://webthumb.bluga.net/
218 - http://www.page2images.com/
219 - http://www.shrinktheweb.com/
220 - http://www.thumbalizr.com/
221 - http://www.url2picture.com/
224 Other website screenshot software
225 =================================
226 - https://github.com/microweber/screen