ftp_mdtm()

Что такое ftp_mdtm()?

Функция ftp_mdtm() — это встроенная функция PHP, которая возвращает время последнего изменения отдельного файла на FTP-сервере. «mdtm» расшифровывается как modification time («время изменения») — это прямое отображение команды FTP-протокола MDTM.

Она особенно полезна, когда нужно синхронизировать файлы, обнаруживать изменения или решать, нужно ли повторно загружать файл: вместо того чтобы скачивать весь файл только для проверки его актуальности, можно сначала запросить у сервера его временну́ю метку.

Функция принимает два параметра:

1. ftp — идентификатор соединения, возвращаемый функцией ftp_connect().
2. remote_file — путь к файлу на сервере.

Функция возвращает время последнего изменения в виде Unix-метки времени (количество секунд с 1970-01-01 UTC). В случае ошибки — файл не существует, путь указывает на директорию или соединение недействительно — функция возвращает -1.

ftp_mdtm() работает только с обычными файлами. Многие серверы отклоняют команду MDTM для директорий, поэтому вызов функции для папки, как правило, возвращает -1.

Синтаксис ftp_mdtm()

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

Тип resource использовался вплоть до PHP 7. Начиная с PHP 8.1, FTP-соединения представлены объектами (FTP\Connection), поэтому первый аргумент является экземпляром FTP\Connection — однако вы по-прежнему передаёте то, что вернула ftp_connect(), поэтому существующий код продолжает работать без изменений.

Функции необходимо активное FTP-соединение. Она не переключает пассивный режим автоматически; если ваша сеть находится за файрволом или NAT, вызовите ftp_pasv($ftp, true) после авторизации и до запроса временно́й метки.

Базовое использование

Для использования ftp_mdtm() сначала подключитесь с помощью ftp_connect() и авторизуйтесь с помощью 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);

Преобразование метки времени в читаемую дату

Поскольку ftp_mdtm() возвращает «сырую» Unix-метку времени, её почти всегда форматируют с помощью date() перед выводом пользователю. Преобразование — это обычный PHP, который работает где угодно без необходимости FTP-сервера:

<?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";

Вывод:

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

Команда MDTM возвращает время в UTC. Используйте gmdate() (или явно задайте часовой пояс), чтобы отображаемое время не сдвигалось незаметно под влиянием локального часового пояса сервера. Полный список символов формата смотрите в date().

Обработка ошибок в ftp_mdtm()

Поскольку функция возвращает -1 в случае ошибки, проверяйте это значение с помощью строгого оператора сравнения ===. Нестрогое сравнение == также совпадало бы с false и другими ложными значениями, скрывая реальные результаты:

<?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";
}

Типичный сценарий: загрузка только при наличии изменений

Основная причина вызова ftp_mdtm() — избежать повторной загрузки неизменённого файла. Сравните временну́ю метку на сервере с временем изменения локального файла:

<?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";
}

Этот подход делает зеркалирование и резервное копирование эффективными: байты передаются только тогда, когда серверная копия действительно новее.

Подводные камни

• Поддержка зависит от сервера. Команда MDTM не входит в исходный стандарт FTP, поэтому некоторые старые или ограниченные серверы не реализуют её и всегда возвращают -1, даже для существующих файлов.
• Директории возвращают -1. Используйте ftp_nlist() для получения содержимого директории.
• Часовой пояс. Метки времени задаются в UTC; используйте gmdate() для форматирования, чтобы избежать неожиданного смещения.
• Нужен также размер файла? Используйте в паре с ftp_size().

Заключение

ftp_mdtm() возвращает Unix-метку времени последнего изменения файла на FTP-сервере, что делает её основным инструментом для обнаружения изменений и инкрементальной синхронизации. Не забывайте проверять значение ошибки -1 с помощью ===, форматировать результат с помощью date() или gmdate() и включать пассивный режим, если этого требует ваша сеть.

Практика