Struggling with VirtualDocumentRoot

Today's blog is a techie special so the rest of you can move right along. I've been struggling today with Apache's mod_vhost_alias and the VirtualDocumentRoot directive. It's actually a very neat enhancement to Apache: it lets you define vhosts by pattern. So you say:

<VirtualHost nnn.nnn.nnn.nnn:80>
    VirtualDocumentRoot /var/www/hosts/%0/www
    VirtualScriptAlias  /var/www/hosts/%0/cgi-bin
</VirtualHost>

And when it gets an HTTP request on interface nnn.nnn.nnn.nnn for the domain name <domain_name> it tries to serve it from the directory /var/www/hosts/<domain_name>/www - or whatever directory you configure (you can do cleverer things too but this is enough for me).

This is exceptionally cool as it means you don't have to create a new entry for every vhost you add, simply create a new directory tree and off it goes. You don't even need to restart Apache, which you have to when you add a vhost explicitly.

So I did this. And it worked.

And then I put in a little PHP test script, running phpinfo() just to check it all looked OK from PHP.

It didn't. DOCUMENT_ROOT wasn't set to the directory from which the pages were being served (as set by VirtualDocumentRoot). How odd. After some scratching about I discovered that this is a long running feud within the Apache community.

See this bug where it's discussed. Essentially the developers claim it's not a bug "Don't trust the DOCUMENT_ROOT variable. It's always only reflecting the value of the DocumentRoot directive, which is by intention, because it's consistent".

That's all well and good but me and many other developers, including big players, rely on it.

This is unsurprising. The PHP manual defines 'DOCUMENT_ROOT' as "The document root directory under which the current script is executing, as defined in the server's configuration file." No mention of "oh, and by the way you can't trust it".

Thankfully there is a solution. It's an almighty kludge but it does work. You use php_admin_value auto_prepend_file to run a bit of PHP before any PHP you run which "fixes" DOCUMENT_ROOT. See the last entry in the bug report for more on this.