ftp_get()

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

ftp_get() — встроенная функция PHP, которая скачивает файл с FTP-сервера и записывает его в локальный файл на вашей машине. Она является аналогом ftp_put() для чтения (тогда как ftp_put() выполняет загрузку на сервер). Используйте её всякий раз, когда нужно получить файл (резервную копию, лог, отчёт) с удалённого сервера по FTP.

На этой странице описывается, что делает ftp_get(), её параметры и возвращаемое значение, полный рабочий процесс (подключение → вход → загрузка → закрытие), обработка ошибок, а также типичные ловушки (режим передачи, пассивный режим и возобновление частичной загрузки).

Параметры

ftp_get() принимает пять параметров — три обязательных и два необязательных:

Возвращаемое значение

Функция возвращает boolean: true при успехе, false при ошибке. Всегда проверяйте его — неудавшаяся загрузка не выбрасывает исключение по умолчанию.

FTP_BINARY и FTP_ASCII

FTP_BINARY передаёт файл байт за байтом и подходит почти для всего: изображений, PDF, архивов, исполняемых файлов и большинства текстовых файлов. FTP_ASCII выполняет автоматическое преобразование окончаний строк между соглашениями сервера и клиента, поэтому используйте его только для файлов с обычным текстом, где это преобразование действительно нужно. Использование FTP_ASCII для бинарного файла его повредит, поэтому при сомнениях выбирайте FTP_BINARY.

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

bool ftp_get ( resource $ftp_stream , string $local_file , string $remote_file [, int $mode = FTP_BINARY [, int $resumepos = 0 ]] )

Примечание: в PHP 8.1+ тип resource для FTP-соединений был заменён объектом Ftp\Connection, а параметр mode стал необязательным (по умолчанию FTP_BINARY). Сигнатура с устаревшим resource сохранена для обратной совместимости — менять существующий код не нужно.

Использование ftp_get()

Чтобы использовать ftp_get(), сначала установите соединение с помощью ftp_connect() и пройдите аутентификацию через ftp_login(). Полный процесс выглядит так:

Скачивание файла с помощью ftp_get()

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

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

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

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

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

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

ftp_get() возвращает false при ошибке, а не выбрасывает исключение, поэтому проверяйте возвращаемое значение явно. Распространённые причины ошибок — отсутствие удалённого файла, недостаточные права доступа или локальный путь, в который нет прав на запись. PHP также генерирует предупреждение, которое можно перехватить для логирования:

Получение причины неудачной загрузки

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

@ подавляет необработанное предупреждение PHP, чтобы вы могли сформировать собственное сообщение, а error_get_last() по-прежнему предоставляет детали ошибки для лога.

Возобновление прерванной загрузки

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

Возобновление загрузки с resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

Возобновление надёжно работает только с FTP_BINARY и на серверах, поддерживающих команду REST. Для больших передач можно также обратиться к неблокирующему варианту ftp_nb_get(), который скачивает в фоне, позволяя скрипту выполнять другую работу.

Связанные функции

• ftp_put() — загружает локальный файл на сервер (обратная операция к ftp_get()).
• ftp_fget() — скачивает файл в уже открытый файловый дескриптор, а не по пути.
• ftp_size() — получает размер удалённого файла перед скачиванием.
• ftp_connect() и ftp_login() — открывают и аутентифицируют соединение.
• ftp_close() — закрывает соединение по завершении работы.

Итоги

ftp_get() скачивает удалённый файл по FTP и сохраняет его локально, возвращая true при успехе и false при ошибке. Сначала установите соединение и войдите в систему, предпочитайте FTP_BINARY, если вам специально не нужно преобразование окончаний строк ASCII, включайте пассивный режим за брандмауэром и всегда проверяйте возвращаемое значение, чтобы ошибки не проходили незамеченными.

Практика