Common Web Server Integrations

PHP does not usually listen for public HTTP requests by itself in production. A web server receives the request first, serves static files when it can, and hands PHP scripts to a PHP runtime such as PHP-FPM, LSAPI, FastCGI, or an Apache module.

The integration matters because many PHP failures happen before framework code runs: wrong document root, bad FastCGI parameters, missing front-controller routing, file permission problems, or a mismatch between the web server and the PHP-FPM pool.

The shared shape

Most PHP web deployments have the same basic flow:

Browser -> Web server -> PHP runtime -> Application front controller

For a modern framework application, the public document root should usually be the public/ directory, not the project root. The web server should serve real static files directly and send everything else to public/index.php.

<?php

declare(strict_types=1);

$serverSoftware = $_SERVER['SERVER_SOFTWARE'] ?? 'CLI or unknown server';
$documentRoot = $_SERVER['DOCUMENT_ROOT'] ?? 'not running through a web server';
$scriptFilename = $_SERVER['SCRIPT_FILENAME'] ?? 'no script filename';

echo 'Server: ' . $serverSoftware . PHP_EOL;
echo 'Document root: ' . $documentRoot . PHP_EOL;
echo 'Script filename: ' . $scriptFilename . PHP_EOL;

// Example output from CLI:
// Server: CLI or unknown server
// Document root: not running through a web server
// Script filename: no script filename

This diagnostic is simple, but it often confirms whether PHP is running through the server you think it is.

Apache

Apache can run PHP in more than one way. Older setups may use mod_php, where PHP runs inside Apache worker processes. Many modern Apache setups use FastCGI with PHP-FPM through mod_proxy_fcgi.

A framework-style Apache configuration commonly uses DocumentRoot plus rewrite rules:

DocumentRoot /var/www/app/public

<Directory /var/www/app/public>
    AllowOverride All
    Require all granted
</Directory>

If .htaccess is used, AllowOverride must permit the rewrite rules. If rewrites are disabled, URLs such as /account/settings may return 404 even though the PHP application is correct.

Nginx

Nginx does not embed PHP. It normally passes PHP requests to PHP-FPM over a Unix socket or TCP port.

server {
    root /var/www/app/public;
    index index.php;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

The important pieces are root, try_files, SCRIPT_FILENAME, and fastcgi_pass. A mistake in any of those can cause downloaded PHP files, 404 responses, 502 responses, or "Primary script unknown" errors.

Caddy

Caddy has a compact PHP-FPM integration:

example.test {
    root * /var/www/app/public
    php_fastcgi unix//run/php/php8.3-fpm.sock
    file_server
}

Caddy is common in modern small deployments because automatic HTTPS and concise configuration reduce setup work. The same core checks still apply: correct public root, correct PHP-FPM socket, and correct front-controller routing.

LiteSpeed and OpenLiteSpeed

LiteSpeed and OpenLiteSpeed commonly run PHP through LSAPI, often branded as LiteSpeed SAPI. They are popular in shared hosting and some high-performance hosting environments.

As a developer, you are most likely to meet LiteSpeed through a hosting panel. The practical checks are the PHP version selected for the site, enabled extensions, document root, rewrite support, and whether the host has separate per-site PHP settings.

IIS

On Windows servers, IIS usually integrates PHP through FastCGI. The key settings are the site root, handler mapping for .php, the configured php-cgi.exe, and URL Rewrite rules for front-controller applications.

IIS is less common in many PHP teams than Nginx or Apache, but it appears in organisations with Windows server infrastructure. Do not assume Linux paths, Unix sockets, or Apache rewrite syntax apply there.

Lighttpd

Lighttpd can pass PHP requests to FastCGI. You may see it on lightweight systems, appliances, older deployments, or constrained servers. The same principles apply: static files are served by the web server, PHP scripts are passed to a runtime, and front-controller routing must be configured deliberately.

Debugging integration failures

Start with the failure mode:

• PHP source downloads in the browser: the web server is serving .php as a static file instead of passing it to PHP
• 404 for application routes: front-controller routing or rewrites are wrong
• 502 or 503: the web server cannot reach PHP-FPM or the PHP runtime is failing
• "Primary script unknown": the FastCGI SCRIPT_FILENAME path is wrong
• assets load but application fails: document root may be right, but PHP handoff or environment is wrong
• application exposes .env or source files: document root is probably the project root instead of public/

What you should be able to do

After this lesson, you should be able to describe how a web server hands requests to PHP, identify the public document root, recognise Apache/Nginx/Caddy/LiteSpeed/IIS/Lighttpd at a high level, and debug common integration mistakes before blaming application code.