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