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
98 We want to create a screenshot of ``http://example.org/`` in size 400x300,
99 using the browser size of 1024x768::
101 http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
103 Phancap's config file contains::
109 Our parameters are thus:
116 ``url`` ``http://example.org/``
121 At first, we need to add parameters ``atimestamp`` and ``atoken``.
122 ``atimestamp`` is the current unix timestamp.
123 ``atoken`` is our user name: ``user``.
125 Now the parameter list is sorted:
130 ``atimestamp`` ``1396353987``
136 ``url`` ``http://example.org/``
139 The parameters are raw-url-encoded. The only value that changes is the url,
140 it becomes ``http%3A%2F%2Fexample.org%2F``.
142 Concatenating the name/value pairs leads to the following string::
144 atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
146 Creating the HMAC digest with sha1, the calculated string and our key
147 ``secret`` gives us the following string::
149 9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
151 This is the signature; it gets appended the URL as ``asignature`` parameter.
157 - `cutycapt <http://cutycapt.sourceforge.net/>`_
158 - imagemagick's ``convert``
160 - PEAR's ``System.php``
163 =======================
164 Technical brainstorming
165 =======================
167 Tools to make website screenshots
168 =================================
169 - `cutycapt <http://cutycapt.sourceforge.net/>`_
170 - `khtml2png <http://khtml2png.sourceforge.net/>`_ (outdated)
171 - `phantomjs <http://phantomjs.org/>`_
172 - `python-webkit2png <https://github.com/AdamN/python-webkit2png/>`_
173 - `wkhtmltopdf <http://code.google.com/p/wkhtmltopdf/>`_
180 Page request parameters
181 -----------------------
183 - bwidth (browser width / resolution)
184 - bheight (browser height / resolution)
185 - delay (capture X seconds after page loaded)
186 - useragent (user agent header string)
187 - accepted languages (Accept-Language header)
188 - cookie (set cookie data)
189 - referer (custom referer header)
190 - post data (send POST data as if filled out a form)
192 Screenshot configuration
193 ------------------------
194 - width (of thumbnail)
195 - height (of thumbnail)
196 - output format (jpg, png, pdf)
197 - mode: screen or page (full page height or screen size only)
199 - quality (jpeg image quality)
203 - callback URL (to notify when screenshot is ready)
204 - sync/async (wait for response or just get a 202 accepted)
205 - cache (to force a fresh screenshot with cache=0,
206 otherwise seconds the cache may be old)
208 - token (md5 hash of query string)
210 API parameter sources
211 ---------------------
212 - http://api1.thumbalizr.com/
213 - http://url2png.com/docs/
214 - http://webthumb.bluga.net/apidoc
215 - http://www.page2images.com/Create-website-screenshot-online-API
216 - http://browshot.com/api/documentation
219 Other website screenshot services
220 =================================
221 - http://browsershots.org/
222 - http://browshot.com/
223 - http://ctrlq.org/screenshots/
225 - http://url2png.com/
226 - http://usersnap.com/
227 - http://websnapr.com/
228 - http://webthumb.bluga.net/
229 - http://www.page2images.com/
230 - http://www.shrinktheweb.com/
231 - http://www.thumbalizr.com/
232 - http://www.url2picture.com/
235 Other website screenshot software
236 =================================
237 - https://github.com/microweber/screen