README.rst

   1 ************************************
   2 phancap - website screenshot service
   3 ************************************
   4
   5 Web service (API) to create website screenshots.
   6
   7 Self-hosted and written in PHP. Caching included.
   8
   9
  10 *phancap* is useful for:
  11
  12 - Show screenshots for websites in your bookmarking application
  13 - Archive a HTML page as PDF for later viewing
  14
  15
  16 .. contents::
  17
  18
  19 ========
  20 Features
  21 ========
  22
  23 * Configurable browser size
  24 * Configurable screenshot size
  25 * Clip and full page rendering (full height)
  26 * JPG, PNG and PDF output (PDFs are searchable)
  27 * Authentication
  28 * Can run on a normal web server without GUI. See dependencies_.
  29
  30
  31 .. note::
  32     *phancap* does not rely on a "real" browser.
  33     Currently ``cutycapt`` is utilized, which uses a pretty bare webkit to render
  34     the pages.
  35     Do not expect pixel-for-pixel identical rendering as your desktop browser.
  36
  37
  38 ===============
  39 Getting started
  40 ===============
  41
  42 Basic setup
  43 ===========
  44 #. Download the ``.phar`` file and put it onto your web server
  45 #. Open the phar file in your browser
  46
  47    If you only see text beginning with ``<?php``, you need to
  48    `setup .phar file extension handling`__ in your web server first.
  49 #. Click the "setup check" link
  50 #. Fix all errors that are reported
  51 #. Run ``phancap.phar/get.php?url=cweiske.de`` and see the screenshot
  52
  53 __ http://cweiske.de/tagebuch/phar-webserver.htm
  54
  55
  56 Advanced setup
  57 ==============
  58 With the basic setup, everyone may use your server to create website
  59 screenshots.
  60 You may want to change that or simply change some default settings.
  61
  62 #. Create a config file ``phancap.phar.config.php``
  63 #. Edit it; see the configuration_ options.
  64
  65
  66 ==============
  67 URL parameters
  68 ==============
  69 ``get.php`` supports the following parameters:
  70
  71 Browser parameters
  72 ==================
  73 ``url``
  74   Website URL
  75 ``bwidth``
  76   Browser width (default: 1024)
  77 ``bheight``
  78   Browser height (default: none)
  79
  80 Screenshot parameters
  81 =====================
  82 ``swidth``
  83   Screenshot width (default: none (no scaling))
  84 ``sheight``
  85   Screenshot height (default: none)
  86 ``sformat``
  87   Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
  88 ``smode``
  89   Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
  90 ``smaxage``
  91   Maximum age of screenshot in seconds.
  92   ISO 8601 duration specifications accepted:
  93
  94   - ``P1Y`` - 1 year
  95   - ``P2W`` - 2 weeks
  96   - ``P1D`` - 1 day
  97   - ``PT4H`` - 4 hours
  98
  99   The configuration file defines a minimum age that the user cannot undercut
 100   (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
 101
 102 Authentication parameters
 103 =========================
 104 ``atimestamp``
 105   Time at which the request URL was generated (unix timestamp)
 106 ``atoken``
 107   Access token (username)
 108 ``asignature``
 109   Signature for the request. See the authentication_ section.
 110
 111
 112 =============
 113 Configuration
 114 =============
 115 phancap looks at several places for its configuration file:
 116
 117 #. ``phancap.phar.config.php`` in the same directory as your
 118    ``phancap.phar`` file.
 119
 120 #. ``/etc/phancap.php``
 121
 122
 123 Configuration variables
 124 =======================
 125 ``$cacheDir``
 126   Full file system path to image cache directory
 127 ``$cacheDirUrl``
 128   Full URL to cache directory
 129 ``$access``
 130   Credentials for access control
 131
 132   ``true`` to allow access to anyone, ``false`` to disable it completely.
 133   ``array`` of username - secret key combinations otherwise.
 134 ``$cutycapt['parameters']``
 135   Additional command line parameters for cutycapt.
 136   Can be used to e.g. enable browser plugins:
 137
 138   ``$cutycapt['parameters'] = '--plugins=on';``
 139 ``$cutycapt['maxWaitTime']``
 140   Maximal time in seconds to wait for cutycapt to finish rendering.
 141   Defaults to 30 seconds.
 142 ``$disableSetup``
 143   Disable ``setup.php`` which will leak file system paths
 144 ``$redirect``
 145   Redirect to static image urls after generating them
 146 ``$timestampmaxAge``
 147   How long a signature timestamp is considered valid. 2 days default.
 148 ``$screenshotMaxAge``
 149   Cache time of downloaded screenshots.
 150
 151   When the file is as older than this, it gets re-created.
 152 ``$screenshotMinAge``
 153   Minimum age of a screeshot. 1 hour default.
 154
 155   A user cannot set the max age parameter below it.
 156
 157
 158
 159 ==============
 160 Authentication
 161 ==============
 162 Creating screenshots of websites is a resource intensive process.
 163 To prevent unauthorized access to the service, phancap supports authentication
 164 via a signature parameter similar to OAuth's ``oauth_signature``.
 165
 166 Phancap's configuration file may contain a ``$access`` variable:
 167
 168 ``true``
 169   Everyone is allowed to access the service
 170 ``false``
 171   Nobody is allowed to access the service
 172 ``array``
 173   A list of usernames that are allowed to request screenshots, together
 174   with their secret keys (password)::
 175
 176     $access = array(
 177        'user1' => 'secret1',
 178        'user2' => 'secret2',
 179     )
 180
 181 The signature algorithm is as follows:
 182
 183 #. Parameters ``atimestamp`` (current unix timestamp) and
 184    ``atoken`` (username) have to be added to the URL parameters
 185
 186 #. URL parameters are normalized as described in
 187    `OAuth Parameters Normalization`__:
 188
 189    #. Sort parameters list by name
 190    #. Name and value are `raw-url-encoded`__
 191    #. Name and value are concatenated with ``=`` as separator
 192    #. The resulting strings are concatenated with ``&`` as separator
 193
 194 #. URL parameter string is used together with the secret key
 195    to create a `HMAC-SHA1`__ digest
 196
 197 #. Digest is appended to the URL as ``asignature``
 198
 199 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
 200 __ http://tools.ietf.org/html/rfc5849#section-3.6
 201 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
 202
 203
 204 Example
 205 =======
 206
 207 .. note::
 208
 209     The ``docs/`` directory contains an example PHP client implementation.
 210
 211 We want to create a screenshot of ``http://example.org/`` in size 400x300,
 212 using the browser size of 1024x768::
 213
 214     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
 215
 216 Phancap's config file contains::
 217
 218     $access = array(
 219         'user' => 'secret'
 220     );
 221
 222 Our parameters are thus:
 223
 224 ============== =====
 225 Name           Value
 226 ============== =====
 227 ``swidth``     ``400``
 228 ``sheight``    ``300``
 229 ``url``        ``http://example.org/``
 230 ``bwidth``     ``1024``
 231 ``bheight``    ``768``
 232 ============== =====
 233
 234 At first, we need to add parameters ``atimestamp`` and ``atoken``.
 235 ``atimestamp`` is the current unix timestamp.
 236 ``atoken`` is our user name: ``user``.
 237
 238 Now the parameter list is sorted:
 239
 240 ============== =====
 241 Name           Value
 242 ============== =====
 243 ``atimestamp`` ``1396353987``
 244 ``atoken``     ``user``
 245 ``bheight``    ``768``
 246 ``bwidth``     ``1024``
 247 ``sheight``    ``300``
 248 ``swidth``     ``400``
 249 ``url``        ``http://example.org/``
 250 ============== =====
 251
 252 The parameters are raw-url-encoded. The only value that changes is the url,
 253 it becomes ``http%3A%2F%2Fexample.org%2F``.
 254
 255 Concatenating the name/value pairs leads to the following string::
 256
 257     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 258
 259 Creating the HMAC digest with sha1, the calculated string and our key
 260 ``secret`` gives us the following string::
 261
 262     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 263
 264 This is the signature; it gets appended to the URL as ``asignature`` parameter.
 265
 266
 267 ============
 268 Dependencies
 269 ============
 270 - External tools:
 271
 272   - `cutycapt <http://cutycapt.sourceforge.net/>`_
 273   - `imagemagick's <http://www.imagemagick.org/>`_ ``convert``
 274   - ``xvfb-run``
 275
 276 - Libraries (already included in the ``.phar``):
 277
 278   - PEAR's ``System.php``
 279
 280
 281 =======
 282 License
 283 =======
 284 ``phancap`` is licensed under the `AGPL v3`__ or later.
 285
 286 __ http://www.gnu.org/licenses/agpl.html
 287
 288
 289 ========
 290 Homepage
 291 ========
 292 Web site
 293    http://cweiske.de/phancap.htm
 294
 295 Source code
 296    http://git.cweiske.de/phancap.git
 297
 298    Mirror: https://github.com/cweiske/phancap
 299
 300
 301 ======
 302 Author
 303 ======
 304 Written by Christian Weiske, cweiske@cweiske.de
 305
 306
 307 ============
 308 Alternatives
 309 ============
 310 All of those are open source:
 311
 312 * http://code.google.com/p/browsershots/ (python)
 313 * https://github.com/gre/screenshot-webservice (scala)