ftp_connect()

Функция PHP ftp_connect()

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

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

Синтаксис

ftp_connect(string $hostname, int $port = 21, int $timeout = 90): FTP\Connection|false

Возвращаемое значение. При успехе возвращается объект соединения — экземпляр FTP\Connection начиная с PHP 8.1, или resource в более ранних версиях. При ошибке возвращается false, поэтому результат необходимо всегда проверять перед использованием.

Примечание: ftp_connect() устанавливает незашифрованное соединение — учётные данные и данные передаются в открытом виде. Для всего, что передаётся через публичный интернет, предпочтительнее использовать ftp_ssl_connect() (FTPS).

Полный рабочий процесс: соединение → вход → закрытие

Типичный сеанс открывает соединение, проходит аутентификацию, выполняет работу, затем закрывает дескриптор:

<?php

// 1. Open the control connection (does not log you in)
$conn = ftp_connect('ftp.example.com', 21, 30);

// 2. Authenticate
ftp_login($conn, 'username', 'password');

// 3. Many servers behind NAT/firewalls need passive mode
ftp_pasv($conn, true);

// 4. Do some work — e.g. upload a file
ftp_put($conn, 'backup.sql', 'local-backup.sql', FTP_BINARY);

// 5. Always release the connection
ftp_close($conn);

Каждый шаг соответствует отдельной функции: ftp_login() выполняет аутентификацию, ftp_pasv() переключает пассивный режим, ftp_put() и ftp_get() передают файлы, а ftp_close() закрывает соединение.

Обработка неудачного соединения

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

<?php

$conn = ftp_connect('ftp.example.com', 21, 30);
if ($conn === false) {
    // Wrong host, blocked port 21, or DNS/network failure
    exit("Could not reach the FTP server.\n");
}

if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    exit("Login failed — check the username and password.\n");
}

echo "Connected and authenticated.\n";

// ... transfer files ...

ftp_close($conn);

Используйте строгое сравнение === false вместо !$conn. Для ftp_connect() оба варианта ведут себя одинаково, но === false делает намерение явным и позволяет избежать сюрпризов, когда функция может законно возвращать пустое, но истинное значение.

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

• Расширение FTP может быть отключено. Функции ftp_* требуют PHP, скомпилированного с --enable-ftp (или пакета php-ftp). Проверяйте с помощью if (!function_exists('ftp_connect')) { ... }, если важна переносимость.
• Пассивный режим. Если ftp_connect() и ftp_login() выполняются успешно, но листинги или передачи зависают, сервер, скорее всего, находится за файрволом — переключитесь в пассивный режим с помощью ftp_pasv($conn, true) после входа.
• Соединение — это не аутентификация. Возвращённый дескриптор означает лишь, что TCP-канал открыт. Неверный пароль вызовет ошибку позже, на этапе ftp_login().
• Без префикса ftp://. Передавайте просто имя хоста; схема подразумевается функцией.

Обзор всего набора FTP-инструментов см. в справочнике PHP FTP functions.

Практика