ftp_login()

Функция PHP ftp_login() выполняет аутентификацию пользователя на FTP-сервере. Это второй шаг практически каждой FTP-сессии: сначала открывается соединение с помощью ftp_connect(), затем вызывается ftp_login() для идентификации перед тем, как можно будет просматривать, загружать или скачивать файлы. На этой странице объясняются параметры, возвращаемое значение, способы обработки ошибки входа и наиболее распространённые ловушки (пассивный режим, защищённые соединения и безопасность учётных данных).

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

ftp_login() — встроенная функция PHP, которая выполняет вход на FTP-сервер с указанными именем пользователя и паролем. Соединение должно быть уже открыто — ftp_login() не устанавливает соединение самостоятельно; она выполняет аутентификацию через существующий дескриптор соединения.

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

1. ftp — идентификатор соединения, возвращённый функцией ftp_connect() (или ftp_ssl_connect()).
2. username — имя пользователя для входа. Используйте anonymous для анонимных FTP-серверов.
3. password — пароль для входа. Для анонимного входа принято указывать адрес электронной почты.

Функция возвращает boolean: true при успешном входе, false при неудаче (неверные учётные данные, учётная запись без права на вход и т.д.).

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

ftp_login(FTP\Connection $ftp, string $username, string $password): bool

Примечание: До PHP 8.1 первый параметр являлся ресурсом (resource), возвращаемым функцией ftp_connect(). Начиная с PHP 8.1, это объект FTP\Connection. Код вызова при этом не изменяется — меняется только базовый тип.

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

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

<?php

// 1. Open a connection (returns false on failure)
$conn = ftp_connect('ftp.example.com');

if ($conn === false) {
    exit("Could not connect to the FTP server.\n");
}

// 2. Authenticate
if (ftp_login($conn, 'username', 'password')) {
    echo "Logged in successfully.\n";
    // ... work with files here ...
} else {
    echo "Login failed: check the username and password.\n";
}

// 3. Always close the connection when finished
ftp_close($conn);

Три вызова — connect, login, close — обрамляют любую FTP-задачу. Смотрите ftp_close(), чтобы понять, почему важно освобождать дескриптор.

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

ftp_login() возвращает false при неудачном входе, но также генерирует предупреждение PHP. В production-среде обычно нужно подавить это предупреждение и самостоятельно решить, что делать. Используйте оператор @ для подавления предупреждения и ветвьтесь по возвращаемому значению:

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false) {
    echo "Login failed.\n";
} elseif (@ftp_login($conn, 'username', 'wrong-password') === false) {
    echo "Login failed.\n";
} else {
    echo "Login successful.\n";
}

При недоступном хосте или неверных учётных данных будет выведено Login failed. вместо краша или вывода необработанного предупреждения на страницу.

Пассивный режим и защищённый вход

Два момента, которые вызывают затруднения после успешного входа:

• Пассивный режим. Многие серверы (и большинство NAT/firewall-конфигураций) требуют пассивного режима для передачи данных, например просмотра директорий и загрузки файлов. Включите его с помощью ftp_pasv() — но только после успешного вызова ftp_login(), не до.
• Шифрование. Обычный FTP передаёт имя пользователя и пароль в открытом виде. Предпочтительнее использовать FTP через SSL/TLS, открывая соединение с помощью ftp_ssl_connect(); ftp_login() при этом работает точно так же.

<?php

$conn = ftp_ssl_connect('ftp.example.com'); // encrypted control channel

if ($conn && ftp_login($conn, 'username', 'password')) {
    ftp_pasv($conn, true);                   // enable passive mode after login
    // ... transfer files ...
    ftp_close($conn);
}

Типичные ошибки

• Никогда не хардкодьте учётные данные в коде, который вы коммитите. Читайте их из переменных окружения или файла конфигурации, не попадающего под контроль версий.
• ftp_login() не устанавливает соединение. Если передать ей строку с именем хоста вместо дескриптора соединения, возникнет TypeError. Всегда сначала вызывайте ftp_connect().
• Возврат true означает лишь успешную аутентификацию. Это ничего не говорит о правах доступа — последующая загрузка файла может завершиться неудачей, если учётная запись не имеет прав на запись.

Заключение

ftp_login() выполняет аутентификацию открытого FTP-соединения по имени пользователя и паролю, возвращая true или false. Всегда сначала устанавливайте соединение, проверяйте возвращаемое значение, при необходимости включайте пассивный режим после входа и предпочитайте зашифрованное соединение в production-среде. Полный набор связанных функций смотрите в справочнике PHP FTP.

Практика