ftp_ssl_connect()

Понимание PHP-функции ftp_ssl_connect()

Функция ftp_ssl_connect() открывает соединение explicit FTPS (FTP через SSL/TLS) с FTP-сервером. Это защищённый аналог ftp_connect(): обе функции возвращают дескриптор соединения, который передаётся другим функциям семейства ftp_*, однако ftp_ssl_connect() переводит управляющий канал на зашифрованную TLS-сессию, чтобы учётные данные и команды не передавались в открытом виде.

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

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

Функция ftp_ssl_connect() устанавливает защищённое SSL/TLS-соединение с FTP-сервером. Для её работы PHP должен быть собран с расширениями ftp и openssl. Функция принимает три параметра:

1. host: имя FTP-сервера для подключения.
2. port: номер порта. Параметр необязательный, по умолчанию используется порт 21.
3. timeout: тайм-аут попытки подключения в секундах. Параметр необязательный, по умолчанию равен 90 секундам.

Примечание: По умолчанию PHP проверяет SSL-сертификаты с помощью системного набора CA-сертификатов. В производственной среде убедитесь, что CA-сертификаты актуальны, чтобы избежать ошибок при подключении.

Функция возвращает дескриптор FTP-соединения при успехе (объект FTP\Connection в PHP 8.1+ или ресурс в более ранних версиях) и false при ошибке.

FTPS против SFTP — выберите правильный протокол

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

• FTPS (именно с ним работает данная функция) — это протокол FTP, обёрнутый в TLS. Используйте ftp_ssl_connect() и остальные функции семейства ftp_*.
• SFTP — это подсистема SSH, не имеющая ничего общего с FTP. PHP не может обращаться к ней через функции ftp_* — для этого используется расширение ssh2_* или библиотека, например phpseclib.

Если ваш сервер поддерживает только SSH/SFTP, ftp_ssl_connect() не сможет к нему подключиться.

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

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

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

resource ftp_ssl_connect ( string $host [, int $port = 21 [, int $timeout = 90 ]] )

Функция ftp_ssl_connect() принимает три параметра, из которых обязательным является только host. Параметр port задаёт номер порта для подключения, а параметр timeout — тайм-аут попытки подключения в секундах.

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

Чтобы использовать функцию ftp_ssl_connect(), достаточно вызвать её и передать необходимые параметры. Пример:

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

<?php

// Set up a secure SSL-encrypted FTP connection
$conn = ftp_ssl_connect('ftp.example.com', 21, 60);

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Perform FTP operations

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

В этом примере мы устанавливаем защищённое SSL-соединение с FTP-сервером с помощью функции ftp_ssl_connect(). Затем выполняем вход с учётными данными FTP, используя функцию ftp_login(). После входа можно выполнять необходимые FTP-операции. В конце закрываем FTP-соединение с помощью функции ftp_close().

Полный пример загрузки файла для продакшена

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

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

<?php

$host = 'ftp.example.com';
$user = 'username';
$pass = 'password';

// 1. Open the secure connection (false on failure)
$conn = ftp_ssl_connect($host, 21, 30);
if ($conn === false) {
    exit("Could not connect to {$host}\n");
}

// 2. Authenticate
if (!ftp_login($conn, $user, $pass)) {
    ftp_close($conn);
    exit("Login failed for {$user}\n");
}

// 3. Passive mode — almost always required for FTPS behind a firewall
ftp_pasv($conn, true);

// 4. Upload a local file in binary mode
if (ftp_put($conn, 'remote/report.csv', 'local/report.csv', FTP_BINARY)) {
    echo "Upload succeeded\n";
} else {
    echo "Upload failed\n";
}

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

Ключевые привычки здесь — проверка возвращаемого значения каждого вызова и включение пассивного режима с помощью ftp_pasv() — именно они делают FTPS надёжным на практике. Без пассивного режима передача данных за брандмауэрами часто зависает, так как сервер пытается открыть обратное соединение, которое клиент не может принять.

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

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

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

<?php

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

if ($conn === false) {
    echo "Failed to establish a secure SSL-encrypted connection to the FTP server.\n";
} else {
    // Perform FTP operations

    // Close the FTP connection
    ftp_close($conn);
}

Правильная обработка ошибок и проверка возвращаемого значения функции позволяют гарантировать успешное выполнение FTP-операций с использованием ftp_ssl_connect().

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

• Полученный дескриптор не означает, что вы вошли в систему. ftp_ssl_connect() только открывает зашифрованный канал; перед любой операцией необходим успешный вызов ftp_login().
• Забыть про пассивный режим. Большинство операций передачи данных зависает за брандмауэрами или NAT, если не вызвать ftp_pasv($conn, true) после входа.
• Путать FTPS с SFTP. Как отмечалось выше, данная функция не может работать с SSH/SFTP-сервером.
• Проверяйте наличие функции. Она доступна только при компиляции PHP с расширениями ftp и openssl. Используйте function_exists('ftp_ssl_connect'), если не можете гарантировать наличие этих расширений.
• Implicit FTPS (порт 990) не поддерживается. ftp_ssl_connect() реализует только explicit FTPS. Для implicit FTPS используйте обёртку потоков или специализированную библиотеку.

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

• ftp_connect() — открыть обычное (незашифрованное) FTP-соединение.
• ftp_login() — аутентификация после подключения.
• ftp_pasv() — переключение пассивного режима передачи.
• ftp_get() / ftp_put() — скачивание и загрузка файлов.
• ftp_close() — закрытие соединения.
• Обзор FTP в PHP — полное семейство FTP-функций.

Заключение

Функция ftp_ssl_connect() является защищённой точкой входа в FTP-инструментарий PHP: она открывает explicit FTPS-соединение, чтобы учётные данные и команды передавались по TLS, а не в открытом виде. Используйте её в паре с проверяемым ftp_login(), включайте пассивный режим и проверяйте каждое возвращаемое значение — это обеспечит надёжный и безопасный рабочий процесс передачи файлов. Если удалённый сервер использует SSH/SFTP вместо FTPS, воспользуйтесь расширением ssh2_*.

Практика