File Uploads in PHP: Secure End-to-End Design

Secure file uploads in PHP are not about accepting a form and moving a file to the server. An attachment can become an execution vector, an information leak, a resource-exhausting upload, or a document that is inaccessible when the business process needs it. The design must cover the full lifecycle: receipt, validation, storage, processing, access authorization, auditing, and deletion.

Define the business contract before accepting files

The first control is not technical: it is limiting the need each attachment fulfills. Proof of identity, an invoice, and a profile image have different formats, owners, retention periods, and access permissions. Grouping them under a generic “upload file” option makes it harder to apply appropriate controls.

For each document type, define an explicit contract:

• Which formats are required and which are excluded.
• Maximum size, maximum number of attachments per operation, and cumulative quota per account or case.
• Who can upload it, at what process stage, and whether they can replace or delete it.
• What automated validation and human review it requires.
• Who can view it, download it, or request a new version.
• How long it is retained and which event triggers its deletion.

This contract prevents accepting files “just in case.” It also makes it possible to distinguish a validation failure, which the user can correct, from a business constraint, such as trying to attach a document when the case is already closed.

Why the extension and declared type are not enough

The original filename extension and the type sent in $_FILES['type'] are client-provided data. They are useful as supplementary interface information, but they do not prove the content. Renaming a file is trivial, and a client can send any HTTP header.

Technical validation must use defense in depth. In PHP, detect the type from the received bytes using mechanisms such as finfo; then apply format-specific validators when the risk or use case requires it. For an image that will be displayed, identifying it as an image is not enough: it is advisable to decode it with a suitable library and generate a new representation. For a PDF or office document, validate the expected structure with specialized tools in an isolated environment.

An allowlist is safer than a blocklist. If the use case supports JPEG and PNG, reject everything else rather than trying to enumerate dangerous formats. Compressed files require additional control: a compressed size limit does not limit expansion during decompression. Set limits for expanded size, number of entries, nesting depth, and analysis time.

Names are also untrusted. Do not use them as a path, identifier, or physical name. Sequences such as ../, control characters, double extensions, and name collisions must become irrelevant because the system generates its own opaque identifier.

Controlled receipt and partial error handling

Before processing content, limit the input surface. Configure consistent limits in PHP, the web server, and the reverse proxy. If the proxy accepts 100 MB but PHP allows 10 MB, behavior will be confusing; if PHP allows more than intended, an attacker can consume memory, temporary disk space, or worker connections.

Explicitly control individual size, total request size, number of files, and upload duration. Check the error code of every $_FILES entry, verify that it comes from an HTTP upload, and treat each attachment as an independent unit. In a multi-file operation, decide in advance whether the outcome is atomic or partial. If partial results are accepted, the response must state precisely which file was received, which was rejected, and why, without exposing internal server details.

Do not process a file directly from a request-controlled path or assume that an interrupted upload is harmless. Incomplete temporary files must be cleaned up, and retries must be idempotent when the product supports them. An operation token or idempotency key prevents creating multiple equivalent attachments after network resubmissions.

Private storage, quarantine, and processing

Binaries must not reside under the application's public directory. Store them in private storage, with least-privilege credentials, and associate each object with a system-generated internal identifier. The database can retain metadata such as owner, business context, detected type, size, cryptographic hash, status, dates, and retention policy. Avoid storing unnecessary personal data in the name or operational logs.

A robust flow separates receipt and availability:

1. The application receives the file and creates a record with status pending or quarantined.
2. The binary is placed in a location inaccessible for downloads.
3. An asynchronous process performs antimalware scanning, deep validation, transformation, or permitted extraction.
4. The result changes to available, rejected, or requires_review.
5. The interface displays the operational status without pretending that an upload is already usable.

Queues reduce response time, but introduce their own failures: duplicate jobs, delayed messages, and failed processors. Design idempotent tasks, retry limits, alerts for stuck items, and a controlled reprocessing path. If scanning is unavailable, the safe alternative is usually to keep the attachment in quarantine, not publish it.

Authorize every download and deliver content without executing it

Knowing an identifier does not grant anyone access. Every download must verify the authenticated identity, its current relationship to the resource, and the business context: membership in an organization, assignment to the case, current role, document status, and time-based restrictions. Do not reuse the authorization that existed when the file was uploaded; permissions may have been revoked afterward.

The download must go through a controller that applies this decision before reading or delegating the object. Signed URLs can be useful for delivery from external storage, but they require limited scope, short expiration, and controls that prevent their issuance for unauthorized resources.

Deliver active types with caution. For documents not intended to be rendered in the browser, use Content-Disposition: attachment. Set the content type based on the validated type, not the extension, and add X-Content-Type-Options: nosniff. A preview is not a simple embedded download: it must use transformed representations, isolate potentially active content, and avoid disclosing internal paths.

Auditing, recovery, and testing before production

Log relevant events: creation, replacement, status change, download, deletion, scan error, and permission change. The log must contain the actor, time, resource, and result, but does not need to store the binary or duplicate sensitive data. Protect these events from alteration and define who can access them.

Recovery requires knowing what happens if storage, the database, or the processor fails. Do not mark a document as available until the binary and its metadata are consistent. Design reconciliation tasks to detect records without an object, orphaned objects, and items that remain in quarantine for too long.

Release checklist

• Permitted formats address a documented use case and are validated by content.
• There are limits for size, quantity, time, and compressed-file expansion.
• Original names do not determine paths or physical names.
• Binaries are stored outside the public directory and go through quarantine when appropriate.
• Downloads reevaluate authorization and do not expose internal paths.
• Malformed files, duplicates, interrupted uploads, revoked permissions, and storage failures are tested.
• There is monitoring for rejections, stuck jobs, delivery errors, and consumed capacity.
• Retention, deletion, and audit policies have an operational owner.

Turning an upload into a flow with states and controls may seem more costly than using an uploads directory. However, it reduces improvised decisions when a suspicious file, an access claim, or an operational disruption arises. That traceability is part of the product, not a later addition.