Built-In Web Server

PHP includes a development HTTP server in the CLI SAPI. It is the quickest way to send a real HTTP request to a small PHP project without first configuring Apache, Nginx, Caddy, or PHP-FPM.

Use it for local learning, controlled demonstrations, and focused application checks. PHP's manual explicitly says it is not a full-featured server and must not be used on a public network.

Start With An Explicit Document Root

From a project containing public/index.php, run:

php -S 127.0.0.1:8000 -t public

The parts have separate jobs:

• -S starts the built-in server;
• 127.0.0.1:8000 selects the listening address and port;
• -t public makes public the document root.

Open http://127.0.0.1:8000/ or request it from another terminal:

curl -i http://127.0.0.1:8000/

curl -i shows response headers as well as the body. Press Ctrl+C in the server terminal to stop the process.

Always specify the intended document root. Without -t, PHP serves from the directory in which the command starts. Accidentally starting in a project root can place source, local configuration, dependency metadata, tests, and storage paths inside the server's visible tree.

A common layout is:

project/
|-- config/
|-- public/
|   |-- assets/
|   `-- index.php
|-- src/
|-- storage/
`-- vendor/

Only public/ is meant to receive direct HTTP requests. Application code can require files outside it, but the server should not expose those paths as static resources.

Create A Front Controller

A front controller is the PHP file through which application requests enter:

<?php

declare(strict_types=1);

header('Content-Type: text/plain; charset=utf-8');

$method = $_SERVER['REQUEST_METHOD'] ?? 'UNKNOWN';
$uri = $_SERVER['REQUEST_URI'] ?? '/';

echo "PHP development server\n";
echo "SAPI: " . PHP_SAPI . "\n";
echo "Method: {$method}\n";
echo "URI: {$uri}\n";

A request to http://127.0.0.1:8000/orders?page=2 can produce:

PHP development server
SAPI: cli-server
Method: GET
URI: /orders?page=2

PHP_SAPI is cli-server, not cli and not fpm-fcgi. The server is launched by the CLI binary but handles HTTP requests through its dedicated SAPI.

Understand Default File Resolution

When a requested static file exists under the document root, the built-in server serves it with a standard MIME type. For example, public/assets/site.css is available at /assets/site.css.

When a request does not map directly to an existing file, the server can search for index.php or index.html in the requested directory and then through parent directories up to the document root. If it finds an index file, trailing URI content may be exposed through $_SERVER['PATH_INFO']; otherwise the response is 404 Not Found. This means a missing path can execute a parent index.php, and that application must set 404 itself when the route is unknown.

Do not build application routing around every detail of that fallback. A router script or framework front controller gives the project an explicit routing rule and is easier to test consistently.

Inspect An HTTP Request Correctly

$_SERVER['REQUEST_URI'] includes the path and query string. Separate the path before matching routes:

<?php

declare(strict_types=1);

$requestUri = $_SERVER['REQUEST_URI'] ?? '/';
$path = parse_url($requestUri, PHP_URL_PATH);

if (!is_string($path)) {
    http_response_code(400);
    echo "Invalid request URI\n";
    exit;
}

header('Content-Type: application/json; charset=utf-8');

echo json_encode([
    'method' => $_SERVER['REQUEST_METHOD'] ?? 'UNKNOWN',
    'path' => $path,
    'query' => $_GET,
    'sapi' => PHP_SAPI,
], JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT) . PHP_EOL;

Test different request shapes instead of refreshing only one browser page:

curl -i "http://127.0.0.1:8000/search?q=php&page=2"
curl -i -X POST http://127.0.0.1:8000/orders
curl -i -H "Accept: application/json" http://127.0.0.1:8000/

A browser often makes additional requests such as /favicon.ico, so more than one access-log line does not necessarily mean the application duplicated a request.

Use A Router Script For Application Routes

A router script runs at the start of every request. If it returns false, the built-in server serves the requested resource normally. Otherwise, the router's output becomes the response.

Place router.php in the project root:

<?php

declare(strict_types=1);

$publicRoot = realpath(__DIR__ . '/public');
$requestUri = $_SERVER['REQUEST_URI'] ?? '/';
$path = parse_url($requestUri, PHP_URL_PATH);

if ($publicRoot === false || !is_string($path)) {
    http_response_code(400);
    echo "Invalid server configuration or request path.\n";
    exit;
}

$decodedPath = rawurldecode($path);

if (str_contains($decodedPath, "\0")) {
    http_response_code(400);
    echo "Invalid request path.\n";
    exit;
}

$candidatePath = $publicRoot
    . DIRECTORY_SEPARATOR
    . ltrim($decodedPath, "/\\");
$candidate = realpath($candidatePath);
$isPublicFile = $candidate !== false
    && str_starts_with($candidate, $publicRoot . DIRECTORY_SEPARATOR)
    && is_file($candidate);

if ($isPublicFile) {
    return false;
}

require $publicRoot . DIRECTORY_SEPARATOR . 'index.php';

Start it with both the document root and router:

php -S 127.0.0.1:8000 -t public router.php

The -t public part is essential. return false delegates to the server, and the server must resolve that request inside the same intended public root.

The realpath() boundary check prevents a path containing parent-directory segments from being treated as an approved public file. The built-in server also enforces its document root, but the router should not make security decisions through naive string concatenation.

Set Status And Headers Before Output

The built-in server follows normal PHP response rules. Send status and headers before body output:

<?php

declare(strict_types=1);

http_response_code(404);
header('Content-Type: application/json; charset=utf-8');

echo json_encode(
    ['error' => 'Route not found'],
    JSON_THROW_ON_ERROR,
) . PHP_EOL;

Check the complete response with curl -i. A JSON body saying "not found" is not enough if the HTTP status remains 200 OK. Clients, caches, monitors, and tests use the status separately from the body.

Do not enable permissive cross-origin headers merely to hide a browser error. CORS, cookies, sessions, redirects, uploads, and authentication still need deliberate application rules during local development.

Know Which Configuration Is Running

The built-in server uses the CLI PHP executable and its configuration. Inspect them before diagnosing an extension or limit:

php -v
php --ini
php -m

A project can apply a documented one-process override:

php -d display_errors=1 -S 127.0.0.1:8000 -t public router.php

Development error display can help locally, but response bodies containing warnings can corrupt JSON or reveal paths and credentials. Production should log appropriate detail and return controlled error responses.

A successful request here does not prove that PHP-FPM has the same extensions, INI files, environment variables, operating-system user, filesystem permissions, or timeouts. The next lesson separates those server architectures.

Expect One Blocking Process By Default

The normal built-in server runs one single-threaded process. If one request waits on a slow network call, lock, stream, or deliberate sleep(), another request can stall behind it. This makes the server unsuitable for load tests, concurrency conclusions, long-running workers, or production traffic.

PHP supports an experimental PHP_CLI_SERVER_WORKERS setting on platforms other than Windows, but the manual still warns that the server and that worker feature are not for production. Use the same architecture as the deployed system when concurrency behaviour matters.

Bind To The Smallest Necessary Interface

Use 127.0.0.1 for local-only IPv4 access:

php -S 127.0.0.1:8000 -t public

Binding to all IPv4 interfaces exposes the process to networks that can reach your machine:

php -S 0.0.0.0:8000 -t public

Only do that for a controlled need, such as testing from another device on a trusted network. A development application may contain debug output, weak test credentials, destructive routes, or no TLS. A firewall prompt is a security decision, not an installation formality.

If the port is already occupied, stop the other process or choose another unprivileged port such as 8080. Do not terminate an unknown process merely to reclaim port 8000.

Distinguish Query, Form, And Raw Body Data

Different HTTP inputs reach PHP through different interfaces. Query parameters such as ?page=2 populate $_GET. A form sent as application/x-www-form-urlencoded or multipart/form-data can populate $_POST. A JSON request body does not automatically become $_POST; read php://input and decode it deliberately.

<?php

declare(strict_types=1);

header('Content-Type: application/json; charset=utf-8');

$contentType = $_SERVER['CONTENT_TYPE'] ?? '';
$rawBody = file_get_contents('php://input');

if ($rawBody === false) {
    http_response_code(400);
    echo json_encode(['error' => 'Request body could not be read'], JSON_THROW_ON_ERROR);
    exit;
}

$decoded = str_starts_with($contentType, 'application/json')
    ? json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR)
    : null;

echo json_encode([
    'query' => $_GET,
    'form' => $_POST,
    'json' => $decoded,
], JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT) . PHP_EOL;

A production endpoint also needs a body-size limit, JSON exception handling, schema validation, authentication, and authorization. The built-in server does not make incoming data trustworthy; it only makes local requests convenient.

Exercise the body explicitly:

curl -i -X POST \
  -H "Content-Type: application/json" \
  --data '{"sku":"BOOK-42","quantity":2}' \
  http://127.0.0.1:8000/orders

Read The Server Terminal

Keep the server terminal visible while testing. It reports startup details, accepted connections, request methods and paths, statuses, and startup failures such as an occupied port or missing document root. PHP warnings may also appear there depending on configuration.

Use those logs to correlate one client request with one server response, but do not treat them as a production logging system. They lack the structured context, retention, access controls, rotation, and central collection expected from application and infrastructure logs.

When a request fails, separate the layers:

Change one layer at a time. Confirm the listening process, request URL, HTTP response, router decision, and application code in that order. Restart the server after changing startup flags or environment variables; editing a PHP source file normally takes effect on the next request, but process-level configuration does not change inside an already running server.

Do Not Treat It As Production Parity

The built-in server does not reproduce a production reverse proxy or web-server stack. It does not validate:

• Nginx, Apache, or Caddy routing rules;
• FastCGI parameters and PHP-FPM pools;
• TLS certificates and HTTP-to-HTTPS redirects;
• proxy headers and trusted-proxy configuration;
• production users, groups, and file permissions;
• process supervision, restarts, health checks, or scaling;
• production caching, compression, buffering, and request limits.

It answers a narrower question: how does this PHP application behave when reached through a simple local HTTP server?

What You Should Be Able To Do

After this lesson, you should be able to start the server with an explicit public root, inspect requests and responses with curl, route application paths through a front controller, delegate safe static files, set correct statuses and headers, and explain why cli-server is not PHP-FPM or a production web server.

The authoritative reference is PHP's built-in web server manual.