Run a PHP Web Server to Quickly Serve Local Files and Folders From Any Directory
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
returnsfalse
for a particular HTTP request, then the requested resource (file) will be processed and served. - If
page.php
does not returnfalse
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.