ftp_fput()

What is ftp_fput()?

The ftp_fput() function is a PHP built-in function that uploads a file to the FTP server. The function takes five parameters:

1. ftp_stream: The connection identifier returned by the ftp_connect() function.
2. remote_file: The remote file name to which the file should be uploaded.
3. local_file: A file handle resource opened with fopen() that points to the local file to be uploaded.
4. mode (optional): The transfer mode (FTP_ASCII or FTP_BINARY). Defaults to FTP_ASCII.
5. startpos (optional): The starting position in the remote file for the upload. Defaults to 0.

The function returns a boolean value. If the function is successful in uploading the file, it returns true. Otherwise, it returns false.

When to use ftp_fput() instead of ftp_put()

ftp_put() takes a local file path as a string and opens the file for you. ftp_fput() takes an already-open file handle instead. Reach for ftp_fput() when:

• The data you want to upload is not a plain file on disk — for example a temporary stream created with php://temp, or the output of another resource you already have open.
• You need fine control over the read position (combined with the startpos parameter, you can resume an interrupted upload).
• You have already opened the handle for another reason and want to avoid opening the same file twice.

If you just want to upload an existing file by name, ftp_put() is simpler. For non-blocking (asynchronous) uploads, see ftp_nb_fput().

Syntax of ftp_fput()

The syntax of the ftp_fput() function is as follows:

Syntax of ftp_fput()

bool ftp_fput ( resource $ftp_stream , string $remote_file , resource $local_file [, int $mode = FTP_ASCII [, int $startpos = 0 ]] )

Usage of ftp_fput()

To use the ftp_fput() function, you first need to establish a connection to the FTP server using the ftp_connect() function. Here's an example:

Usage of ftp_fput() in PHP

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.");
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die("Login failed.");
}

// Open the local file
$local_file = fopen('/local/directory/local_file.txt', 'r');
if (!$local_file) {
    die("Could not open local file.");
}

// Upload the file to the remote FTP server
if (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_ASCII)) {
    echo "File uploaded successfully.\n";
} else {
    echo "Failed to upload the file.\n";
}

// Close the file handle and FTP connection
fclose($local_file);
ftp_close($conn);

In this example, we establish a connection to the FTP server using the ftp_connect() function and verify it succeeded. Then we log in using our FTP credentials with ftp_login() and check for errors. Next, we open the local file with fopen() to get the required file handle. Finally, we upload the file to the remote FTP server using ftp_fput() and close both the file handle and the FTP connection with ftp_close().

Choosing the transfer mode: FTP_ASCII vs FTP_BINARY

The mode parameter controls how bytes are transferred and matters more than it looks:

• FTP_BINARY transfers the file byte-for-byte, unchanged. Use it for images, archives, executables, PDFs — anything that is not plain text. This is the safe default for almost everything.
• FTP_ASCII translates line endings between the local and remote platforms (e.g. \n ↔ \r\n). It is only appropriate for plain-text files, and using it on binary data will silently corrupt the file.

When you open the local handle, match the fopen() mode to the transfer: use 'rb' (read binary) together with FTP_BINARY so PHP does not alter the bytes on the way in:

<?php

$local_file = fopen('/local/directory/photo.jpg', 'rb');
ftp_fput($conn, 'photo.jpg', $local_file, FTP_BINARY);
fclose($local_file);

Error handling in ftp_fput()

It's important to handle errors properly when using the ftp_fput() function. If the function returns false, it means that the file couldn't be uploaded for some reason. Here's an example of how to handle errors:

Error handling in ftp_fput()

<?php

// Assuming $conn is already established via ftp_connect() and ftp_login()
$local_file = fopen('/local/directory/local_file.txt', 'rb');

if ($local_file === false) {
    echo "Could not open the local file.\n";
} elseif (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_BINARY)) {
    echo "File uploaded successfully.\n";
    fclose($local_file);
} else {
    echo "Failed to upload the file.\n";
    fclose($local_file);
}

Notice the order of the checks: we first confirm that fopen() returned a valid handle, then call ftp_fput(). Calling fclose() on a false handle (which happens if the original example skips the open check) emits a warning, so we only close the handle on the branches where it was actually opened. This keeps the "success" message from ever printing when the upload did not happen.

Common pitfalls

• Passing a path instead of a handle. ftp_fput() expects the resource returned by fopen(), not a filename string. If you have a path, use ftp_put() instead.
• Wrong transfer mode. Uploading a binary file with FTP_ASCII corrupts it. When in doubt, use FTP_BINARY.
• Not closing the handle. Always call fclose() once the transfer is done to free the resource.
• Passive mode. Behind a firewall, many servers require passive mode. Call ftp_pasv($conn, true) after logging in if uploads hang.

Conclusion

The ftp_fput() function uploads a file to an FTP server from an open file handle, making it the right choice when your data already lives in a stream rather than at a fixed path on disk. Pair it with the correct transfer mode, check both the fopen() and ftp_fput() return values, and close your handles, and it will serve reliably in your PHP projects.

Practice