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 ``smaxage``
  35   Maximum age of screenshot in seconds.
  36   ISO 8601 duration specifications accepted:
  37
  38   - ``P1Y`` - 1 year
  39   - ``P2W`` - 2 weeks
  40   - ``P1D`` - 1 day
  41   - ``PT4H`` - 4 hours
  42
  43   The configuration file defines a minimum age that the user cannot undercut
  44   (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
  45
  46 Authentication parameters
  47 =========================
  48 ``atimestamp``
  49   Time at which the request URL was generated (unix timestamp)
  50 ``atoken``
  51   Access token (username)
  52 ``asignature``
  53   Signature for the request. See the authentication section.
  54
  55
  56 ==============
  57 Authentication
  58 ==============
  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``.
  62
  63 Phancap's configuration file may contain a ``$access`` variable:
  64
  65 ``true``
  66   Everyone is allowed to access the service
  67 ``false``
  68   Nobody is allowed to access the service
  69 ``array``
  70   A list of usernames that are allowed to request screenshots, together
  71   with their secret keys (password)
  72
  73 The signature algorithm is as follows:
  74
  75 #. Parameters ``atimestamp`` (current unix timestamp) and
  76    ``atoken`` (username) have to be added to the URL parameters
  77
  78 #. URL parameters are normalized as described in
  79    `OAuth Parameters Normalization`__:
  80
  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
  85
  86 #. URL parameter string is used together with the secret key
  87    to create a `HMAC-SHA1`__ digest
  88
  89 #. Digest is appended to the URL as ``asignature``
  90
  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
  94
  95
  96 Example
  97 =======
  98 We want to create a screenshot of ``http://example.org/`` in size 400x300,
  99 using the browser size of 1024x768::
 100
 101     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
 102
 103 Phancap's config file contains::
 104
 105     $access = array(
 106         'user' => 'secret'
 107     );
 108
 109 Our parameters are thus:
 110
 111 ============== =====
 112 Name           Value
 113 ============== =====
 114 ``swidth``     ``400``
 115 ``sheight``    ``300``
 116 ``url``        ``http://example.org/``
 117 ``bwidth``     ``1024``
 118 ``bheight``    ``768``
 119 ============== =====
 120
 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``.
 124
 125 Now the parameter list is sorted:
 126
 127 ============== =====
 128 Name           Value
 129 ============== =====
 130 ``atimestamp`` ``1396353987``
 131 ``atoken``     ``user``
 132 ``bheight``    ``768``
 133 ``bwidth``     ``1024``
 134 ``sheight``    ``300``
 135 ``swidth``     ``400``
 136 ``url``        ``http://example.org/``
 137 ============== =====
 138
 139 The parameters are raw-url-encoded. The only value that changes is the url,
 140 it becomes ``http%3A%2F%2Fexample.org%2F``.
 141
 142 Concatenating the name/value pairs leads to the following string::
 143
 144     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 145
 146 Creating the HMAC digest with sha1, the calculated string and our key
 147 ``secret`` gives us the following string::
 148
 149     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 150
 151 This is the signature; it gets appended the URL as ``asignature`` parameter.
 152
 153
 154 ============
 155 Dependencies
 156 ============
 157 - `cutycapt <http://cutycapt.sourceforge.net/>`_
 158 - imagemagick's ``convert``
 159 - ``xvfb-run``
 160
 161
 162
 163 =======================
 164 Technical brainstorming
 165 =======================
 166
 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/>`_
 174 - wkhtmltoimage
 175
 176
 177 Possible parameters
 178 ===================
 179
 180 Page request parameters
 181 -----------------------
 182 - url
 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)
 191
 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)
 198   - page aka fullpage
 199 - quality (jpeg image quality)
 200
 201 Misc
 202 ----
 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)
 207 - api key
 208 - token (md5 hash of query string)
 209
 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
 217
 218
 219 Other website screenshot services
 220 =================================
 221 - http://browsershots.org/
 222 - http://browshot.com/
 223 - http://ctrlq.org/screenshots/
 224 - http://grabz.it/
 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/
 233
 234
 235 Other website screenshot software
 236 =================================
 237 - https://github.com/microweber/screen