Using PHP's Built-in Server: A Quick Guide to `php -S`

2 min read . August 21, 2024

When developing PHP applications, especially during the early stages or for small projects, setting up a full-fledged web server like Apache or Nginx can feel like overkill. Fortunately, PHP comes with a built-in server that you can start with a single command: php -S. This lightweight server is perfect for local development and testing. We’ll explore how to use the php -S command, its options, and best practices.

What is `php -S`?

The php -S command starts a built-in web server provided by PHP. This server is designed for development purposes and offers a quick and easy way to serve PHP files without the need for complex server configurations.

Starting the PHP Built-in Server

To start the server, navigate to the root directory of your PHP project in your terminal and run the following command:

php -S localhost:8000

This command tells PHP to start the server on localhost and listen on port 8000. Once the server is running, you can access your PHP application by opening http://localhost:8000 in your web browser.

Serving Specific Directories

By default, the php -S command serves files from the directory you are currently in. If you want to serve files from a different directory, specify the path to that directory:

php -S localhost:8000 -t /path/to/your/directory

Here, the -t option specifies the document root, which is the directory where your PHP files are located.

Custom Router Scripts

One of the powerful features of the built-in server is its support for custom router scripts. A router script is a PHP file that handles all incoming requests, which is particularly useful for single-page applications or custom routing logic.

To use a custom router, create a PHP file (e.g., router.php) with the following content:

<?php
if (php_sapi_name() === 'cli-server') {
    $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
    if (file_exists(__DIR__ . $path)) {
        return false; // Serve the requested resource as-is.
    }
}

// Your custom routing logic
require __DIR__ . '/index.php';

Then, start the server with the router script:

php -S localhost:8000 router.php

This setup ensures that the built-in server will first check if the requested file exists and serve it directly. If the file doesn’t exist, the server will pass the request to index.php (or your main application entry point).

Benefits of Using `php -S`

Simplicity: No need to install or configure a full web server.
Portability: Works on any machine with PHP installed.
Quick Setup: Ideal for rapid prototyping and small projects.
Debugging: Easily combine with PHP’s error reporting for quick debugging.

Limitations of the Built-in Server

While convenient, the built-in server has some limitations:

Single-threaded: It handles one request at a time, making it unsuitable for high-concurrency environments.
Not for Production: It’s meant for development only and lacks the robustness required for production environments.
Limited Features: It doesn’t support .htaccess files, URL rewriting, or advanced server features provided by Apache or Nginx.

Conclusion

The php -S command is a handy tool for PHP developers, offering a simple way to serve your application during development without the overhead of setting up a full web server. Whether you’re building a small project, testing code, or learning PHP, the built-in server provides a quick and effective way to get up and running.

Tags:

PHP