README.rst

   1 ************************************
   2 phancap - website screenshot service
   3 ************************************
   4
   5 Web service to create website screenshots.
   6
   7 Self-hosted and written in PHP. Caching included.
   8
   9
  10 ==============
  11 URL parameters
  12 ==============
  13 ``get.php`` supports the following parameters:
  14
  15 Browser parameters
  16 ==================
  17 ``url``
  18   Website URL
  19 ``bwidth``
  20   Browser width (default: 1024)
  21 ``bheight``
  22   Browser height (default: none)
  23
  24 Screenshot parameters
  25 =====================
  26 ``swidth``
  27   Screenshot width (default: none (no scaling))
  28 ``sheight``
  29   Screenshot height (default: none)
  30 ``sformat``
  31   Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
  32 ``smode``
  33   Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
  34
  35 Authentication parameters
  36 =========================
  37 ``atimestamp``
  38   Time at which the request URL was generated (unix timestamp)
  39 ``atoken``
  40   Access token (username)
  41 ``asignature``
  42   Signature for the request. See the authentication section.
  43
  44
  45 ==============
  46 Authentication
  47 ==============
  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``.
  51
  52 Phancap's configuration file may contain a ``$access`` variable:
  53
  54 ``true``
  55   Everyone is allowed to access the service
  56 ``false``
  57   Nobody is allowed to access the service
  58 ``array``
  59   A list of usernames that are allowed to request screenshots, together
  60   with their secret keys (password)
  61
  62 The signature algorithm is as follows:
  63
  64 #. Parameters ``atimestamp`` (current unix timestamp) and
  65    ``atoken`` (username) have to be added to the URL parameters
  66
  67 #. URL parameters are normalized as described in
  68    `OAuth Parameters Normalization`__:
  69
  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
  74
  75 #. URL parameter string is used together with the secret key
  76    to create a `HMAC-SHA1`__ digest
  77
  78 #. Digest is appended to the URL as ``asignature``
  79
  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
  83
  84
  85 Example
  86 =======
  87 We want to create a screenshot of ``http://example.org/`` in size 400x300,
  88 using the browser size of 1024x768::
  89
  90     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
  91
  92 Phancap's config file contains::
  93
  94     $access = array(
  95         'user' => 'secret'
  96     );
  97
  98 Our parameters are thus:
  99
 100 ============== =====
 101 Name           Value
 102 ============== =====
 103 ``swidth``     ``400``
 104 ``sheight``    ``300``
 105 ``url``        ``http://example.org/``
 106 ``bwidth``     ``1024``
 107 ``bheight``    ``768``
 108 ============== =====
 109
 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``.
 113
 114 Now the parameter list is sorted:
 115
 116 ============== =====
 117 Name           Value
 118 ============== =====
 119 ``atimestamp`` ``1396353987``
 120 ``atoken``     ``user``
 121 ``bheight``    ``768``
 122 ``bwidth``     ``1024``
 123 ``sheight``    ``300``
 124 ``swidth``     ``400``
 125 ``url``        ``http://example.org/``
 126 ============== =====
 127
 128 The parameters are raw-url-encoded. The only value that changes is the url,
 129 it becomes ``http%3A%2F%2Fexample.org%2F``.
 130
 131 Concatenating the name/value pairs leads to the following string::
 132
 133     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 134
 135 Creating the HMAC digest with sha1, the calculated string and our key
 136 ``secret`` gives us the following string::
 137
 138     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 139
 140 This is the signature; it gets appended the URL as ``asignature`` parameter.
 141
 142
 143 ============
 144 Dependencies
 145 ============
 146 - `cutycapt <http://cutycapt.sourceforge.net/>`_
 147 - imagemagick's ``convert``
 148 - ``xvfb-run``
 149
 150
 151
 152 =======================
 153 Technical brainstorming
 154 =======================
 155
 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/>`_
 163 - wkhtmltoimage
 164
 165
 166 Possible parameters
 167 ===================
 168
 169 Page request parameters
 170 -----------------------
 171 - url
 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)
 180
 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)
 187   - page aka fullpage
 188 - quality (jpeg image quality)
 189
 190 Misc
 191 ----
 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)
 196 - api key
 197 - token (md5 hash of query string)
 198
 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
 206
 207
 208 Other website screenshot services
 209 =================================
 210 - http://browsershots.org/
 211 - http://browshot.com/
 212 - http://ctrlq.org/screenshots/
 213 - http://grabz.it/
 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/
 222
 223
 224 Other website screenshot software
 225 =================================
 226 - https://github.com/microweber/screen