Secure PHP File Uploads: Validation, Private Storage and Safe Downloads

Define a narrow upload contract

The OWASP upload guidance recommends a layered approach: restricted types and sizes, generated filenames, authorised users, protected storage and appropriate content checks. It also warns against trusting a browser-supplied Content-Type as proof of file content.

Write the contract in product terms: who can upload, what purpose the file serves, which formats are necessary, the byte/dimension limits, who can later read it and how long it is kept. An attachment marked private must not quietly become public through the image CDN or a predictable storage URL.

For an illustrative membership application, the avatar feature might accept only small JPEG/PNG images, while identity documents are not accepted at all. That is a deliberate reduction in scope, not a limitation that should be bypassed by renaming a file.

Validate request and PHP upload status before opening the file

PHP's upload documentation describes the upload mechanism and associated configuration. Handle the upload error/status and expected data shape before trusting a temporary path. Enforce a server/proxy request limit as well as application limits so oversized traffic does not reach the expensive stage unchecked.

A validation helper can contribute to the process, but it is not a complete upload controller. The following original example is for a narrow JPEG/PNG feature. Authentication, CSRF protection, rate limiting, safe destination creation and final authorisation still belong around it.

<?php
function inspectAvatarUpload(array $file): array
{
    if (($file['error'] ?? null) !== UPLOAD_ERR_OK
        || !is_string($file['tmp_name'] ?? null)
        || !is_uploaded_file($file['tmp_name'])) {
        throw new InvalidArgumentException('Invalid upload.');
    }
    $bytes = filesize($file['tmp_name']);
    if ($bytes === false || $bytes < 1 || $bytes > 5 * 1024 * 1024) {
        throw new InvalidArgumentException('Avatar exceeds size policy.');
    }
    $mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
    $extensions = ['image/jpeg' => 'jpg', 'image/png' => 'png'];
    if (!is_string($mime) || !isset($extensions[$mime])) {
        throw new InvalidArgumentException('Unsupported avatar type.');
    }
    return [
        'temporaryPath' => $file['tmp_name'],
        'storageName' => bin2hex(random_bytes(16)) . '.' . $extensions[$mime],
        'mime' => $mime,
        'bytes' => $bytes,
    ];
}

The Fileinfo function examines content for classification; it is not a malware-free certificate. The random_bytes API supplies randomness for the generated identifier. A random name helps avoid user-controlled paths but does not make a publicly accessible file private.

Treat content processing as another boundary

A MIME match is only an early check. An avatar pipeline can additionally decode and re-encode a supported raster format with updated libraries and strict dimensions/resource budgets. Handle parser failure without making the original bytes public first.

Do not run unbounded image conversion synchronously for every unauthenticated request. Define limits for dimensions, processing time and concurrency. If processing is asynchronous, use a pending state and publish only the approved derivative. A failed or interrupted job should not leave an orphaned publicly executable file.

SVG, HTML, archives and office documents have different active-content and parsing considerations. Excluding them from an avatar feature is sensible. If the business genuinely requires them elsewhere, design that feature separately instead of adding their extensions to the same allow-list.

Store uploads where the web server cannot execute them

Separate user-controlled storage from application code and deployment files. Resolve destinations from server-owned directories and generated identifiers, not a supplied original filename. Prevent collisions from overwriting unrelated files and use storage permissions appropriate to the account/process model.

The move_uploaded_file documentation explains the uploaded-file move operation and warns that an existing destination can be overwritten. Check its return value and verify the resulting attachment record rather than reporting success before the file and metadata are both established.

If a database update fails after a move, have an explicit recovery policy. If the move fails, do not keep a database row that falsely claims a readable attachment exists. This is an operational consistency problem as well as a security concern.

Recheck authorisation when serving a private attachment

Use a server-controlled attachment ID to locate the stored object. Authenticate the reader and authorise access to that attachment's owning record before returning bytes or a short-lived delivery URL. Never accept an arbitrary filesystem path from the download request.

Choose response content type and disposition for the supported format, with a safe filename policy. Do not cache a private response publicly. Test access after permissions are revoked, after the owning record is deleted and when two tenants have attachments with similar names.

The download boundary is easy to overlook because a random storage name seems difficult to guess. Unpredictability is not the same as checking whether the requesting person is allowed to receive the file.

Verify failure cases, not just one successful photograph

A useful disposable test set includes no file, an oversized file, an unsupported format, a MIME/extension mismatch, a duplicate submission, a storage-permission failure and a denied cross-user download. Check that the application leaves no false success record or unintended public object in each case.

Keep a cleanup policy for expired pending uploads and unused derivatives, while preserving files still referenced by published content or private records. This article proposes controls and test cases; it is not a complete production handler or a claim that the example guarantees file safety. Documentation was checked on 22 October 2026.