Request for Comments: Built-in web server

• Version: 1.0
• Date: 2011-06-020
• Author: Moriyoshi Koizumi <moriyoshi.at.php.net>
• Status: Implemented in 5.4
• First Published at: http://wiki.php.net/rfc/builtinwebserver
• Other formats ..

When it comes to web development, most people wouldn't doubt PHP's best friend is Apache HTTPD Server. Having said that, developers who experienced any of web application frameworks of other scripting languages such as Ruby on Rails and Django may well find it cumbersome to set up httpd.conf just to use it within a development environment as those are most likely accompanied by a tiny web server that can be launched with a simple command line.

While PHP is capable enough to write a standalone web server in, thanks to the enhanced stream APIs, writing it in PHP for each web application framework should not really make sense because it could not be made compatible enough with the standard environment due to difficulty of emulating PHP's per-request resource handling in the main event loop without Runkit.

Therefore, it is natural that CLI version of PHP has a feature that the binary itself can be a web server.

CLI version of PHP will have a new command-line option -S followed by a host address (either in numeric or alphabetic) and a port number delimited by a colon, which will launch a builtin web server listening on the given address and port,

php -S localhost:8000

with the following output:

Server is listening on localhost:8000... Press CTRL-C to quit.

Every request will be shown in the console as well.

Server is listening on localhost:8000... Press CTRL-C to quit.
[Thu Mar  3 05:42:06 2011] ::1:56258: /
[Thu Mar  3 05:42:06 2011] ::1:56259: /?=PHPE9568F34-D428-11d2-A769-00AA001ACF42
[Thu Mar  3 05:42:06 2011] ::1:56260: /?=PHPE9568F35-D428-11d2-A769-00AA001ACF42

The document root can be specified through the -t option. If omitted, the current working directory will be used.

php -S localhost:8000 -t docroot

If a request is made for a directory, the web server will return index.html or index.php if they exist in the directory.

Quite a few number of web applications rely on the URL rewrite feature of the web server to do the custom routing on pretty paths. One can use a router script to emulate the feature. A router script is a script which will be dispatched on every request to the web server and determine how to handle it. If the script returns false, the request is then handled in the default manner. Otherwise, it is supposed to give an appropriate response to the client.

php -S localhost:8000 routing.php

If the path to a file is given, the file will be regarded as a router script and the document root will then be set to the directory where it belongs.

<?php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"]))
    return false; // serve the requested resource as-is.
else
    ...
?>

At the moment, POSIX-compliant OS'es and Windows are supported.

http://gist.github.com/835698

2011-03-03: initial version