PHP post_max_size Explained: Configuration, Limits, and Best Practices

Introduction

The post_max_size directive defines the maximum size of the entire HTTP POST request that PHP accepts. Unlike upload_max_filesize, which limits the size of a single uploaded file, post_max_size applies to the complete request, including uploaded files, form fields, cookies, and other POST data.

A properly configured post_max_size ensures that PHP can process large uploads while protecting the server from excessively large requests.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is post_max_size?

Example:

post_max_size = 128M

This means PHP accepts POST requests up to 128 MB.

If the request exceeds this limit, PHP discards the POST body before the application can access it.

How post_max_size Works

When a browser submits a form, the POST request contains much more than just the uploaded file.

Browser
    │
    ▼
POST Request
    │
    ├── Uploaded File
    ├── Form Fields
    ├── Hidden Inputs
    ├── Cookies
    └── Other POST Data
          │
          ▼
post_max_size Check
          │
          ▼
PHP Application

If the total request size exceeds post_max_size, the request is rejected.

Check the Current Value

php -i | grep post_max_size

Example:

post_max_size => 128M => 128M

Change post_max_size

Open the PHP configuration:

sudo nano /etc/php.ini

Find:

post_max_size = 8M

Modify it:

post_max_size = 128M

Restart PHP-FPM:

sudo systemctl restart php-fpm

Verify the Configuration

php -i | grep post_max_size

Or use:

<?php
phpinfo();

Search for:

post_max_size

post_max_size vs upload_max_filesize

This is the most important section.

Many administrators configure:

upload_max_filesize = 100M
post_max_size = 50M

This configuration does not work.

Although PHP allows a single uploaded file up to 100 MB, the total POST request is limited to 50 MB. As a result, the upload fails before PHP can process it.

A recommended configuration is:

upload_max_filesize = 100M
post_max_size = 128M

The extra space allows room for multipart form data, additional form fields, and request overhead.

Relationship Between Common Upload Settings

These directives work together during file uploads.

Browser
    │
    ▼
Nginx
(client_max_body_size)
    │
    ▼
PHP
    │
    ├── post_max_size
    ├── upload_max_filesize
    ├── memory_limit
    └── max_execution_time
    │
    ▼
Application

The effective upload limit is determined by the smallest applicable restriction in the request path.

Recommended Values

| Application   | upload_max_filesize | post_max_size |
| ------------- | ------------------- | ------------- |
| Small website |                 10M |           16M |
| WordPress     |                 64M |           80M |
| CMS           |                100M |          128M |
| Large uploads |                256M |          300M |

As a general guideline, post_max_size should be slightly larger than upload_max_filesize to accommodate request overhead.

Common Issues

Upload Still Fails

Possible causes include:

post_max_size is smaller than upload_max_filesize.

PHP-FPM has not been restarted.

The wrong php.ini file was modified.

Nginx client_max_body_size is too small.

Empty $_POST or $_FILES

If the request exceeds post_max_size, PHP discards the POST body. As a result, both $_POST and $_FILES may appear empty, even though the browser submitted data.

Best Practices

Always configure post_max_size to be larger than upload_max_filesize.

Keep upload limits appropriate for your application.

Restart PHP-FPM after changing configuration values.

Verify the settings using phpinfo() or php -i.

Remember to check your web server's upload size limits as well.

Conclusion

The post_max_size directive controls the maximum size of an entire HTTP POST request. It works together with upload_max_filesize, memory_limit, and your web server's configuration to determine whether uploads are accepted.

When troubleshooting upload problems, checking only upload_max_filesize is often not enough. Reviewing the complete upload pipeline helps identify configuration mismatches and prevents common upload failures.