silverlining / docs / php.txt

Full commit
PHP Support

PHP support in Silver Lining is experimental.  Meaning, I'm not sure
exactly *how* it should work, or if it is working well.  It also adds
a slightly Pythonesque flare to the request dispatching.

Enabling PHP

To enable PHP, in your ``app.ini`` file, place::

    platform = php
    php_root = site/
    runner = site/runner.php

``platform = php`` indicates that this is a PHP app.  PHP will be
installed on the server if necessary.  No PHP libraries will be
installed!  However if you use, for example, ``service.postgis``, then
the PostgreSQL drivers for PHP will be installed.

Requests that point to a file in ``static/`` will (like with Python)
serve that file directly.  Files that point to something in
``php_root`` (in this example ``site/``) will also be served directly,
so long as they are not ``.php`` files (as it is the norm to mix code
with static files in PHP applications).

*All* PHP requests will go through the runner (``site/runner.php`` in
our example).  This PHP file may direct the request wherever it sees
fit.  If you wish to simply pass it on, you may do so, like::

    $path = silver_call_next("{$silver_base}/DEFAULT.php");
    include $path;

Note if the file isn't found then ``DEFAULT.php`` would have been

Note that ``.htaccess`` files will not work, so if you need that kind
of functionality you'll need to implement it directly in your runner.
This is somewhat easier than it might otherwise be with a PHP
application, because you can be sure that *all* (dynamic) requests
will go through your runner.  But it means if your application has a
sophisticated set of rewrite rules, for example, you'll have to
replicate them in PHP.  This is probably fairly mechanical (you can
turn those rules into PHP regexes), but documentation on how to do
that translation would be extremely helpful.