ftp_put()

Функция PHP ftp_put()

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

Функция ftp_put() вызывается после установки соединения с помощью ftp_connect() и аутентификации через ftp_login().

Синтаксис

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Возвращает true при успехе и false при ошибке.

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

Режим Binary и ASCII

Неправильный выбор режима — наиболее частая причина ситуации «загрузка прошла, но файл повреждён»:

• FTP_BINARY передаёт байты точно как есть. Используйте его для всего по умолчанию — изображений, архивов, PDF, исполняемых файлов и даже текста на практике.
• FTP_ASCII перезаписывает окончания строк (\n ↔ \r\n) в соответствии с целевой платформой. Имеет смысл только для обычного текста и бесшумно уничтожит любой бинарный файл. При сомнениях оставайтесь на FTP_BINARY.

Полная загрузка файла

Всегда проверяйте возвращаемые значения каждого FTP-вызова, а не считайте, что шаг выполнился успешно:

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

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

Обработка ошибок

ftp_put() возвращает false и выдаёт PHP-предупреждение при сбое. Преобразуйте это в понятный и информативный результат, вместо того чтобы допускать утечку случайного предупреждения в вывод:

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Распространённые причины сбоев

• Неправильный порядок аргументов — удалённый и локальный пути перепутаны местами.
• Пассивный режим не установлен — большинству серверов за NAT требуется ftp_pasv($ftp, true) после входа.
• Отсутствует удалённая директория — ftp_put() не создаёт папки; используйте сначала ftp_mkdir().
• Нет прав на запись или превышена квота на стороне сервера.
• Неправильный режим передачи, повреждающий бинарный файл (используйте FTP_BINARY).

Загрузка из открытого потока

Если ваши данные уже представлены в виде открытого дескриптора файла (или поступают из обёртки потока, а не из пути на диске), используйте вместо этого ftp_fput() — она принимает ресурс потока вместо имени локального файла.

Заключение

ftp_put() загружает локальный файл на удалённый FTP-сервер. Запомните три вещи, которые вызывают большинство проблем: передавайте удалённый путь первым, оставайтесь на FTP_BINARY, если нет особой причины использовать ASCII, и проверяйте каждое возвращаемое значение. Для неблокирующих передач, которые не останавливают скрипт, смотрите ftp_nb_put().

Практика