PHP post_max_size vs upload_max_filesize, what is the difference?

PHP post_max_size vs upload_max_filesize, what is the difference?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

PHP post_max_size vs upload_max_filesize, what is the difference?

Silent failures are the bane of any developer's existence. You hit submit on a form expecting a file to appear in your directory, but nothing happens. No error message pops up, no redirect occurs—just a blank page or a 204 No Content response. The most common culprit is often overlooked until you dig into the php.ini configuration.

When investigating these issues, two specific directives demand attention: upload_max_filesize and post_max_size. While they sound similar, their roles in the request lifecycle are distinct, and misunderstanding this relationship leads to confusing scenarios where a file technically fits within one limit but gets rejected by the other.

The Distinction Between File Size and Request Size

To understand how these directives interact, you must view them as a funnel rather than two independent gates.

The upload_max_filesize directive controls the maximum size of files that PHP is willing to process via the file upload mechanism ($_FILES). This limit applies specifically to data parsed by the php://input stream when handling multipart/form-data requests. If you configure this to 20M, PHP will refuse to parse any individual file larger than that threshold, regardless of how much bandwidth or memory is available for the rest of the request.

The post_max_size directive, conversely, sets the absolute ceiling for the entire HTTP POST body. This includes not just uploaded files, but also form fields, JSON payloads in multipart requests, and any other data sent via the POST method.

The Precedence Rule

This is where the confusion often arises: post_max_size must always be greater than or equal to upload_max_filesize.

Imagine a scenario where you set upload_max_filesize = 20M but leave post_max_size at its default (often 8M on many shared hosting environments). You attempt to upload a 15MB PDF. The file passes the first check because it is under 20MB. However, as PHP attempts to read the request body, it hits the post_max_size limit of 8MB. Because the total POST data exceeds this limit, the entire request is truncated or rejected before the file can be fully processed.

Conversely, if you set post_max_size = 20M and upload_max_filesize = 60M, the behavior changes drastically. The post_max_size acts as a hard cap on the total request size. Even if your configuration allows for a massive file upload (upload_max_filesize = 60M), you cannot actually upload a 50MB file because the total POST data (which is just that one file in this case) exceeds the 20MB post_max_size limit.

Handling Multiple Files

The relationship between these two directives becomes critical when dealing with multiple file inputs in a single form. Each file counted against upload_max_filesize, and the sum of all files plus any text fields counted against post_max_size.

Consider a form with three file inputs, each allowing up to 20MB:

  • File 1: 20MB
  • File 2: 20MB
  • File 3: 20MB
  • Total POST Data: ~60MB (plus headers and text fields)

If you configure your php.ini with the following:

upload_max_filesize = 20M
post_max_size = 20M

The user will fail on the very first file. The individual file size is acceptable, but the total request size exceeds the post_max_size limit immediately.

To support three 20MB files simultaneously, your configuration must reflect the cumulative requirement:

upload_max_filesize = 20M
post_max_size = 60M

Here, upload_max_filesize ensures that no single file exceeds 20MB (preventing memory exhaustion if a user tries to upload a 100MB file), while post_max_size provides enough headroom for the aggregate size of multiple large files.

Practical Implementation

When modifying these settings, remember that changes made in php.ini on a shared hosting environment may not take effect until the next server restart or cache clear. If you are managing your own server, use the ini_set function dynamically if you need to adjust limits per-script:

// Check current limits
$upload_limit = ini_get('upload_max_filesize');
$post_limit = ini_get('post_max_size');

// Adjust if necessary (e.g., in a bootstrap file)
ini_set('upload_max_filesize', '50M');
ini_set('post_max_size', '60M');

However, dynamic configuration is generally less performant and should be avoided for high-traffic applications. For production environments, ensure your .htaccess (if using Apache) or Nginx reverse proxy configuration does not inadvertently override these PHP settings. Always verify the effective values using phpinfo() after making changes to confirm that post_max_size strictly exceeds upload_max_filesize.

If you are building a robust application where file handling is central, consider leveraging tools like Laravel. The framework provides elegant ways to handle file uploads with validation, but it relies on these underlying PHP directives being configured correctly first. For more guidance on securing and configuring your environment, resources like https://laravelcompany.com can offer additional context on best practices for modern PHP development.

Our network