ftp_mdtm()

What is ftp_mdtm()?

The ftp_mdtm() function is a PHP built-in function that retrieves the last modified time of a single file on an FTP server. "mdtm" stands for modification time — it maps directly to the FTP protocol's MDTM command.

It is most useful when you want to synchronize files, detect changes, or decide whether to re-download something: instead of pulling the whole file just to see if it is newer than your local copy, you ask the server for its timestamp first.

It takes two parameters:

1. ftp — the connection identifier returned by ftp_connect().
2. remote_file — the path to the file on the server.

The function returns the last modified time as a Unix timestamp (seconds since 1970-01-01 UTC). On failure — the file does not exist, the path points to a directory, or the connection is invalid — it returns -1.

ftp_mdtm() works on regular files only. Many servers reject MDTM for directories, so calling it on a folder typically returns -1.

Syntax of ftp_mdtm()

ftp_mdtm(resource|FTP\Connection $ftp, string $remote_file): int

The resource type was used up to PHP 7. As of PHP 8.1, FTP connections are objects (FTP\Connection), so the first argument is an FTP\Connection instance instead — but you still pass whatever ftp_connect() returned, so existing code keeps working unchanged.

This function needs an active FTP connection. It does not switch on passive mode for you; if your network is behind a firewall or NAT, call ftp_pasv($ftp, true) after logging in and before requesting the timestamp.

Basic usage

To use ftp_mdtm(), first connect with ftp_connect() and authenticate with ftp_login():

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Log in with your FTP credentials
ftp_login($conn, 'username', 'password');

// Enable passive mode (often required behind a firewall)
ftp_pasv($conn, true);

// Get the last modified time of the remote file (a Unix timestamp)
$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

// Close the FTP connection
ftp_close($conn);

Turning the timestamp into a readable date

Because ftp_mdtm() returns a raw Unix timestamp, you almost always format it with date() before showing it to a human. The conversion is plain PHP, so it runs anywhere — no FTP server needed:

<?php

// Pretend ftp_mdtm() returned this timestamp
$last_modified = 1718000000;

echo "Raw timestamp: $last_modified\n";
echo "Formatted (UTC): " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
echo "Year only: " . gmdate('Y', $last_modified) . "\n";

Output:

Raw timestamp: 1718000000
Formatted (UTC): 2024-06-10 06:13:20 UTC
Year only: 2024

MDTM returns the time in UTC. Use gmdate() (or set the timezone explicitly) so the displayed time is not silently shifted by your server's local timezone. See date() for the full list of format characters.

Error handling in ftp_mdtm()

Since the function returns -1 on failure, check for that value with the strict comparison operator ===. A loose == would also match false and other falsy values, hiding real results:

<?php

$last_modified = ftp_mdtm($conn, '/path/to/remote/file.txt');

if ($last_modified === -1) {
    echo "Failed to retrieve the last modified time.\n";
} else {
    echo "Last modified: " . gmdate('Y-m-d H:i:s', $last_modified) . " UTC\n";
}

Common use case: download only if newer

The typical reason to call ftp_mdtm() is to avoid re-downloading an unchanged file. Compare the remote timestamp against your local file's modification time:

<?php

$remote = '/path/to/remote/file.txt';
$local  = 'file.txt';

$remoteTime = ftp_mdtm($conn, $remote);

if ($remoteTime === -1) {
    echo "Could not read remote timestamp.\n";
} elseif (!file_exists($local) || $remoteTime > filemtime($local)) {
    echo "Remote file is newer — downloading.\n";
    ftp_get($conn, $local, $remote, FTP_BINARY);
} else {
    echo "Local copy is up to date — skipping download.\n";
}

This pattern keeps mirrors and backups efficient: you transfer bytes only when the server's copy is actually newer.

Gotchas

• Server support varies. MDTM is not part of the original FTP standard, so some older or restricted servers do not implement it and always return -1, even for files that exist.
• Directories return -1. Use ftp_nlist() to list directory contents instead.
• Timezone. Timestamps are UTC; format with gmdate() to avoid an unexpected offset.
• Need the file size too? Pair it with ftp_size().

Conclusion

ftp_mdtm() retrieves the last-modified Unix timestamp of a file on an FTP server, which makes it the building block for change detection and incremental syncing. Remember to check for the -1 failure value with ===, format the result with date() or gmdate(), and enable passive mode when your network requires it.

Practice