ftp_fput()

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

Функция ftp_fput() — это встроенная функция PHP, которая загружает файл на FTP-сервер. Функция принимает пять параметров:

1. ftp_stream: идентификатор соединения, возвращаемый функцией ftp_connect().
2. remote_file: имя удалённого файла, в который должна быть загружена информация.
3. local_file: дескриптор ресурса файла, открытый с помощью fopen(), указывающий на локальный файл для загрузки.
4. mode (необязательный): режим передачи (FTP_ASCII или FTP_BINARY). По умолчанию — FTP_ASCII.
5. startpos (необязательный): начальная позиция в удалённом файле для загрузки. По умолчанию — 0.

Функция возвращает boolean-значение. Если файл успешно загружен, функция возвращает true. В противном случае она возвращает false.

Когда использовать ftp_fput() вместо ftp_put()

ftp_put() принимает локальный путь к файлу в виде string и самостоятельно открывает файл. ftp_fput() вместо этого принимает уже открытый дескриптор файла. Используйте ftp_fput() в следующих случаях:

• Данные для загрузки не являются обычным файлом на диске — например, это временный поток, созданный с помощью php://temp, или вывод другого ресурса, который у вас уже открыт.
• Необходим точный контроль над позицией чтения (в сочетании с параметром startpos можно возобновить прерванную загрузку).
• Дескриптор уже был открыт по другой причине, и вы хотите избежать повторного открытия того же файла.

Если вы просто хотите загрузить существующий файл по имени, ftp_put() будет проще. Для неблокирующей (асинхронной) загрузки смотрите ftp_nb_fput().

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

Синтаксис функции ftp_fput() выглядит следующим образом:

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

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

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

Чтобы использовать функцию ftp_fput(), сначала необходимо установить соединение с FTP-сервером с помощью функции ftp_connect(). Вот пример:

Использование ftp_fput() в 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);

В этом примере мы устанавливаем соединение с FTP-сервером с помощью функции ftp_connect() и проверяем, что оно установлено успешно. Затем выполняем вход с использованием учётных данных FTP через ftp_login() и проверяем наличие ошибок. Далее открываем локальный файл с помощью fopen(), чтобы получить необходимый дескриптор файла. Наконец, загружаем файл на удалённый FTP-сервер с помощью ftp_fput() и закрываем как дескриптор файла, так и FTP-соединение с помощью ftp_close().

Выбор режима передачи: FTP_ASCII и FTP_BINARY

Параметр mode управляет способом передачи байтов и важнее, чем кажется:

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

При открытии локального дескриптора согласуйте режим fopen() с режимом передачи: используйте 'rb' (чтение в бинарном режиме) вместе с FTP_BINARY, чтобы PHP не изменял байты при чтении:

<?php

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

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

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

Обработка ошибок в 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);
}

Обратите внимание на порядок проверок: сначала убеждаемся, что fopen() вернул допустимый дескриптор, и только потом вызываем ftp_fput(). Вызов fclose() с дескриптором false (что происходит, если исходный пример пропускает проверку открытия) генерирует предупреждение, поэтому дескриптор закрывается только в тех ветвях, где он действительно был открыт. Это предотвращает вывод сообщения об успехе в случае, когда загрузка не произошла.

Распространённые ошибки

• Передача пути вместо дескриптора. ftp_fput() ожидает ресурс, возвращаемый функцией fopen(), а не string с именем файла. Если у вас есть путь, используйте вместо этого ftp_put().
• Неверный режим передачи. Загрузка бинарного файла с FTP_ASCII повреждает его. При сомнениях используйте FTP_BINARY.
• Незакрытый дескриптор. Всегда вызывайте fclose() после завершения передачи, чтобы освободить ресурс.
• Пассивный режим. За брандмауэром многие серверы требуют пассивного режима. Если загрузка зависает, вызовите ftp_pasv($conn, true) после входа в систему.

Заключение

Функция ftp_fput() загружает файл на FTP-сервер из открытого дескриптора файла, что делает её правильным выбором, когда данные уже находятся в потоке, а не по фиксированному пути на диске. Используйте правильный режим передачи, проверяйте возвращаемые значения как fopen(), так и ftp_fput(), закрывайте дескрипторы — и функция будет надёжно служить в ваших PHP-проектах.

Практика