Laravel : How to send image or file to API

Laravel : How to send image or file to API

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

Stefan Bogdanescu

Founder & Senior Architect

The Hidden Bottleneck in File Uploads to Lumen APIs

When building a client-side application that needs to upload an image or file directly to a server-side API, it is tempting to simply pass the file object through your own backend logic before hitting the target endpoint. You might write code like params['image'] = $request->file('image') and expect the data to flow straight through. While this works perfectly fine for JSON payloads where you are forwarding request data, file uploads require a fundamentally different approach. The Lumen API you described handles files correctly at its boundary, but your client-side PHP wrapper is likely stripping the critical metadata required for the move() operation to succeed.

The core issue lies in how HTTP multipart form data is structured. When you construct a request intended for an API that expects a file upload, you are not just sending binary data; you are sending a specific protocol structure. The $_FILES superglobal relies on three distinct pieces of information: the actual file stream, the original filename provided by the client (which the server uses to generate unique paths or validate extensions), and the MIME type.

In your Lumen API code, $request->file('image') extracts this composite object. However, if you are constructing a new request from within another PHP application (a "client" acting as a proxy), you cannot simply grab the file handle and pass it along. The receiving server expects the standard multipart/form-data boundary delimiter to separate fields, and specifically looks for the original filename in the field metadata. If your client-side code attempts to pass the file object directly without re-encoding it into a proper multipart stream or using a library that understands HTTP boundaries, the Lumen API will receive an empty file or a malformed request. The $image->move() method fails silently or throws an exception because the underlying resource is not what the Laravel/Lumen UploadedFile class expects.

To solve this reliably, you must ensure the client-side application constructs a true multipart request. The most robust way to do this in PHP without dealing with raw cURL headers manually is to use the Symfony HTTP Client component or a dedicated HTTP abstraction layer that supports stream rewriting. If you are using a framework like Laravel itself as the client, the Psr\Http\Message\StreamInterface allows you to create a stream from an existing file path and attach it to a new request instance, preserving the original filename.

$stream = fopen($localFilePath, 'r');
$request = \GuzzleHttp\Psr7\Request::create(
    $apiUri, 
    'POST',
    [
        'multipart' => [
            [
                'name'     => 'image',
                'contents' => $stream,
                'filename' => basename($localFilePath), // Crucial for the server to identify the file
                'headers'  => [
                    'Content-Type' => 'application/octet-stream' 
                ]
            ]
        ]
    ]
);

$response = \GuzzleHttp\Client::send($request);

This approach ensures that when the Lumen API runs $request->file('image'), it receives a valid UploadedFile instance containing the original filename and a readable stream. The server then proceeds to move the file to /public/uploads/images/product/. A common pitfall is forgetting to validate the file size on the client side before initiating the upload, which can lead to unnecessary bandwidth consumption if the server-side logic doesn't reject oversized files immediately.

Another consideration is the security implications of using $image->getClientOriginalName() directly in your destination path. While this works for basic functionality, it exposes your application to directory traversal attacks if an attacker uploads a file named ../../etc/passwd. In a production environment, you should sanitize the filename or generate a unique hash (e.g., md5($image->getRealPath())) before appending it to the destination path. This ensures that even if the client manipulates the filename, the file lands safely within your intended directory without overwriting existing assets.

If you prefer not to build the request manually, frameworks like Laravel provide helpers to handle this, but remember that these must be used on the server receiving the data, not necessarily forwarded from an intermediate PHP script unless that script is also using a framework capable of handling multipart streams correctly. For pure Lumen APIs, sticking to raw HTTP clients with proper multipart construction or leveraging packages designed for file forwarding is the standard pattern.

For further insights on building robust APIs and handling file uploads in the Laravel ecosystem, you can refer to the resources available at https://laravelcompany.com.

Our network