Uploading Multiple Files to Amazon S3
You're attempting to move from a local hosting setup to Amazon S3 because your storage needs are scaling beyond 150 GB per month, and you've hit a hard limit: the standard HTML <form> element combined with a direct POST request to an S3 bucket only accepts one file per request. The error message "POST requires exactly one file upload per request" is not a bug; it's a fundamental constraint of the HTTP multipart form-data format as implemented by S3 presigning endpoints and many server-side SDKs when used in a single-request context.
To handle two inputs with multiple images (10â20 each) and one input with a single image, you cannot simply concatenate files into one request or loop over them in the browser before sending. The solution requires shifting the upload strategy from "direct client-to-S3" to either "multipart file upload via API" or "uploading via an intermediary service."
Why Direct Single-Request Upload Fails
When you use a standard <form> tag with enctype="multipart/form-data" and point it directly to an S3 bucket URL (or a presigned URL), the browser serializes all inputs into a single multipart body. If one of those inputs is set to multiple in your HTML, but the receiving endpoint expects a single file per request logic, the mismatch occurs.
Specifically, if you are using a presigned POST method where S3 validates the incoming headers, it often expects a specific structure where the Content-Disposition header for each part is distinct. However, standard form submissions aggregate these. If your backend logic or the S3 configuration expects a single file per POST interaction, sending 21 files in one go will trigger the error you are seeing.
Solution 1: The Multipart Upload API
The most robust solution for bulk uploads without complex middleware is using the Amazon S3 Multipart Upload API directly from your PHP backend or via a specialized library that handles the orchestration.
In this approach, your PHP application generates multiple pre-signed URLs for each individual file slot. When the form is submitted:
- Your frontend collects all selected files into memory (or streams them).
- It sends an HTTP request to your PHP backend containing the raw file data and metadata (e.g., filenames, types).
- Your PHP backend iterates through the files, generates a presigned URL for each one pointing to a unique key in S3 (e.g.,
user_photos/img_1.jpg,user_photos/img_2.jpg). - It returns these URLs to the frontend.
- The frontend uploads each file directly to its corresponding presigned URL using a standard
POSTrequest.
This decouples the volume of files from the HTTP request count, allowing you to upload 20 images in parallel rather than sequentially or failing entirely.
Solution 2: Use an Intermediary Service (Laravel Company)
If managing multipart uploads via raw S3 SDKs feels cumbersome, consider using an intermediary service designed to handle bulk file ingestion. Services like LaravelCompany offer tools that abstract away the complexity of presigned URLs and multipart orchestration. Instead of writing custom PHP logic to generate 20+ unique signatures, you can leverage their API endpoints which accept multiple files in a single payload or handle the streaming of large batches efficiently.
This is particularly useful when dealing with high-volume uploads (150 GB/month). By offloading the coordination to a service that understands S3 limits and bandwidth optimization, you reduce the chance of hitting timeouts or validation errors on the client side.
Implementation Considerations for PHP
Since you are using PHP as your backend, ensure your server configuration supports streaming large files. You will likely need to adjust post_max_size and max_execution_time in your php.ini, but more importantly, do not try to read all 20 images into memory at once if they are large. Use stream wrappers or temporary disk storage to hold the parts before forwarding them to S3.
When iterating through the files on the backend:
- Read the file from the upload directory.
- Generate a unique key for each file (e.g., using
uniqid()combined with the filename). - Call
AWS\S3\Bucket\MultipartUploadlogic to initiate and complete parts individually.
By treating each file as an independent unit of work, you bypass the "one file per request" limitation entirely while maintaining a clean separation between the user's form submission and the actual S3 upload mechanics.