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
  99 .. note::
 100
 101     The ``docs/`` directory contains an example PHP client implementation.
 102
 103 We want to create a screenshot of ``http://example.org/`` in size 400x300,
 104 using the browser size of 1024x768::
 105
 106     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
 107
 108 Phancap's config file contains::
 109
 110     $access = array(
 111         'user' => 'secret'
 112     );
 113
 114 Our parameters are thus:
 115
 116 ============== =====
 117 Name           Value
 118 ============== =====
 119 ``swidth``     ``400``
 120 ``sheight``    ``300``
 121 ``url``        ``http://example.org/``
 122 ``bwidth``     ``1024``
 123 ``bheight``    ``768``
 124 ============== =====
 125
 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``.
 129
 130 Now the parameter list is sorted:
 131
 132 ============== =====
 133 Name           Value
 134 ============== =====
 135 ``atimestamp`` ``1396353987``
 136 ``atoken``     ``user``
 137 ``bheight``    ``768``
 138 ``bwidth``     ``1024``
 139 ``sheight``    ``300``
 140 ``swidth``     ``400``
 141 ``url``        ``http://example.org/``
 142 ============== =====
 143
 144 The parameters are raw-url-encoded. The only value that changes is the url,
 145 it becomes ``http%3A%2F%2Fexample.org%2F``.
 146
 147 Concatenating the name/value pairs leads to the following string::
 148
 149     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 150
 151 Creating the HMAC digest with sha1, the calculated string and our key
 152 ``secret`` gives us the following string::
 153
 154     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 155
 156 This is the signature; it gets appended the URL as ``asignature`` parameter.
 157
 158
 159 ============
 160 Dependencies
 161 ============
 162 - `cutycapt <http://cutycapt.sourceforge.net/>`_
 163 - imagemagick's ``convert``
 164 - ``xvfb-run``
 165 - PEAR's ``System.php``
 166
 167
 168 =======================
 169 Technical brainstorming
 170 =======================
 171
 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/>`_
 179 - wkhtmltoimage
 180
 181
 182 Possible parameters
 183 ===================
 184
 185 Page request parameters
 186 -----------------------
 187 - url
 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)
 196
 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)
 203   - page aka fullpage
 204 - quality (jpeg image quality)
 205
 206 Misc
 207 ----
 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)
 212 - api key
 213 - token (md5 hash of query string)
 214
 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
 222
 223
 224 Other website screenshot services
 225 =================================
 226 - http://browsershots.org/
 227 - http://browshot.com/
 228 - http://ctrlq.org/screenshots/
 229 - http://grabz.it/
 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/
 238
 239
 240 Other website screenshot software
 241 =================================
 242 - https://github.com/microweber/screen