Can anyone give me an example for PHP's CURLFile class?

Can anyone give me an example for PHP's CURLFile class?

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

Stefan Bogdanescu

Founder & Senior Architect

Migrating from Deprecated @filename to CURLFile in PHP 5.5+

If you are maintaining legacy PHP code or updating a stack from version 5.4 to 5.5, you may have encountered a specific deprecation warning regarding file uploads via cURL. The standard approach using the string "@path/to/file" for CURLOPT_POSTFIELDS is no longer supported starting in PHP 5.5.0. This change was introduced because the magic @ prefix provided insufficient metadata to remote servers about the file being uploaded, such as its MIME type.

To resolve the deprecation warning: "The usage of the @filename API for file uploading is deprecated," you must migrate to the CURLFile class. While the PHP documentation for this class offers only a basic overview without detailed examples, implementing it correctly requires understanding how cURL constructs multipart form data.

Constructing the Request

When using curl_setopt() with an array for CURLOPT_POSTFIELDS, PHP automatically converts that array into a multipart/form-data request. To replace the deprecated string syntax, you instantiate a CURLFile object. This class encapsulates the file path and allows you to explicitly define the form field name and the filename that will appear in the HTTP request headers.

The basic instantiation looks like this:

$curlFile = new CURLFile('/path/to/local/file.txt', 'text/plain', 'my-document.txt');

Here, the first argument is the path to the file on your local server. The second argument is the MIME type (e.g., image/png, text/plain). If you omit this or leave it as an empty string, PHP will attempt to guess the type based on the file extension, but specifying it ensures compatibility with stricter remote servers. The third argument defines the name of the file in the remote server's view (e.g., document.pdf), which is distinct from your local filename.

Integrating into Your Upload Logic

Assuming you have a form submitting a file named Filedata, here is how to refactor your cURL initialization block to use the new class:

$ch = curl_init("http://www.remotesite.com/upload.php"); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);

// Define the file metadata explicitly
$uploadData['file'] = new CURLFile(
    $_FILES['Filedata']['tmp_name'], // Local path
    'application/octet-stream',     // MIME type (guess or specify)
    basename($_FILES['Filedata']['name']) // Filename for remote server
);

curl_setopt($ch, CURLOPT_POSTFIELDS, $uploadData); 
echo curl_exec($ch);        
curl_close($ch);

In this example, we create a single-element array $uploadData where the key matches the form field name expected by upload.php. The basename() function is used to extract just the filename from the full path, ensuring the remote server receives the correct identifier.

Handling the Remote Server Side

A common pitfall when migrating occurs on the receiving end. If your remote script (like your upload.php) relies solely on $_FILES['file']['name'], it will work fine. However, older scripts might use basename($_FILES['file']['tmp_name']) to determine the filename for moving the file.

While CURLFile updates the filename metadata sent by the client, the remote server's logic must still trust the data in $_FILES. As long as your PHP version is updated to 5.5 or higher and you are using the CURLFile class on the sending end, the $_FILES superglobal will populate correctly with the filename provided in the third argument of the constructor.

For developers working within the Laravel ecosystem, this logic translates seamlessly into their controller classes when handling file uploads via cURL requests or API integration, ensuring that file metadata remains consistent regardless of the underlying transport mechanism.

Summary of Changes

The migration involves three specific steps:

  1. Instantiate new CURLFile() instead of using "@path".
  2. Pass the local temporary path ($_FILES['...']['tmp_name']) as the first argument.
  3. Ensure the remote server's upload.php reads from $_FILES['field_name']['name'], not the local path directly.

By adopting this class, you eliminate deprecation warnings and ensure your upload scripts remain compatible with future PHP versions that may tighten security around file handling.

Our network