The most basic requirement while working on websites and web apps is the ability to see our results in a web browser. We do this by serving the local source code via a HTTP web server and then visiting http://localhost in our browser to see the results. Traditionally we’d install and configure web servers like Apache or Nginx but if you’re working on a PHP app or a static website and already have PHP installed in your system, you wouldn’t need to go the traditional route.

You can use the built-in PHP web server to quickly serve PHP and other static files (HTML, CSS, images, videos, fonts, etc.) from your current working directory or any other path in your local file system.

Built-in Web Server

The PHP CLI language interpreter ships with a built-in web server that can be fired up like this:

# Serve index.php or index.html from the current working directory
$ php -S localhost:8080

# Serve a specific file
$ php -S localhost:8080 specific-file.php

The syntax of the command looks like this:

$ php [options] -S addr:port [-t docroot]

You can always go through the different options by reading up on man php but as far as serving local files and folders are concerned all we need to know is that pass your desired host (addr) and port to -S and if you want, you can specify the document root with the -t option. If no document root is specified, the current working directory is served.

$ pwd
/home/user

# Serve cwd as docroot
$ php -S 0.0.0.0:8080
PHP 7.2.24-0ubuntu0.18.04.10 Development Server started at Sat Feb  5 09:54:51 2022
Listening on http://0.0.0.0:8080
Document root is /home/rish # docroot
Press Ctrl-C to quit.

# Serve cwd/pub/ as docroot
$ php -S 0.0.0.0:8080 -t pub/
PHP 7.2.24-0ubuntu0.18.04.10 Development Server started at Sat Feb  5 09:55:51 2022
Listening on <http://0.0.0.0:8080>
Document root is /home/user/pub # docroot
Press Ctrl-C to quit

Whenever the document root (http://localhost) or a folder (http://localhost/foo) is accessed via an HTTP request, the web server will look for an index.php or index.html file in the respective file system folder. If none of them are found, the parent directories will be looked up for those files until the document root is reached. Eventually an HTTP 404 Not Found will be thrown if the files aren’t found.

Router Scripts

While passing a specific file to the web server, it is super important to note that the file will be treated as a “router” script in such cases. An example:

$ php -S localhost:8080 page.php

Now regardless of whatever URL that you visit – /foo, /foo/bar.php, /baz.php, /style.css, etc. – page.php will always be executed.

• If page.php returns false for a particular HTTP request, then the requested resource (file) will be processed and served.
• If page.php does not return false for a request then any output produced by itself be returned to the client (browser).

This makes the in-built PHP web server similar to the rewrite modules of other servers like Apache and Nginx. This makes the web server compatible with any PHP web framework (Laravel, Symfony, etc.) that take advantage of URL re-writes to route all the requests through a single index.php and eventually invoke different routes and controllers internally.

File (Extension) Support

The PHP web server can serve the following static file extensions and will send the standard MIME types (content types) while serving them – .3gp, .apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz, .gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz, .m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg, .ogv, .pdf, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text, .tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, and .zip.

Any other extension like .rb (Ruby), .py (Python), etc. will be served off as Content-Type: application/octet-stream which will lead to a file download in the web browser.

Limitations

The PHP web server is easy and quick to setup so that one can get started with serving static and PHP files or even apps written on popular PHP frameworks. There are a few limitations though that we must be aware of:

• The server runs a single-threaded process. This means new requests will “stall” if a previous request is blocked due to performing time consuming operations like network or disk IO, data computation, etc.
• Due to the previous reason, never use it in production environments. For production it is always recommended to use a more sophisticated and scalable web server like Apache, Nginx, etc.