ftp_connect()

Die PHP-Funktion ftp_connect()

ftp_connect() öffnet eine Steuerverbindung zu einem FTP-Server und gibt ein Verbindungs-Handle zurück, das jede andere FTP-Funktion (ftp_login(), ftp_get(), ftp_put(), …) als erstes Argument benötigt. Man kann es sich wie das Anwählen des Servers vorstellen: Der Aufruf öffnet nur den Kanal — er authentifiziert Sie nicht. Sie müssen sich noch mit ftp_login() anmelden, bevor Sie Dateien übertragen können.

Diese Seite behandelt die Syntax, die drei Parameter, einen vollständigen Verbinden-Anmelden-Schließen-Workflow, den Umgang mit Fehlern und die Beziehung von ftp_connect() zu seinem sicheren Pendant, ftp_ssl_connect().

Syntax

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

Rückgabewert. Bei Erfolg erhalten Sie ein Verbindungsobjekt — ab PHP 8.1 eine FTP\Connection-Instanz oder in früheren Versionen eine resource. Bei einem Fehler wird false zurückgegeben, daher muss das Ergebnis immer vor der Verwendung geprüft werden.

Hinweis: ftp_connect() stellt eine unverschlüsselte Verbindung her — Anmeldedaten und Daten werden im Klartext übertragen. Für alles über das öffentliche Internet verwenden Sie stattdessen ftp_ssl_connect() (FTPS).

Ein vollständiger Verbinden → Anmelden → Schließen-Workflow

Eine typische Sitzung öffnet die Verbindung, authentifiziert sich, führt die Arbeit durch und schließt dann das Handle:

<?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);

Jeder Schritt entspricht einer dedizierten Funktion: ftp_login() authentifiziert, ftp_pasv() schaltet den passiven Modus um, ftp_put() und ftp_get() übertragen Dateien, und ftp_close() beendet die Verbindung.

Umgang mit einer fehlgeschlagenen Verbindung

Da ftp_connect() bei einem Fehler false zurückgibt, sollte ein fehlendes Handle als harter Stopp behandelt werden — der Aufruf späterer FTP-Funktionen mit false löst einen TypeError aus. Prüfen Sie sowohl die Verbindung als auch die Anmeldung:

<?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);

Verwenden Sie einen strengen === false-Vergleich statt !$conn. Beide verhalten sich für ftp_connect() gleich, aber === false macht Ihre Absicht deutlich und vermeidet Überraschungen, wenn eine Funktion einen leeren, aber wahren Wert zurückgeben kann.

Häufige Fallstricke

• Die FTP-Erweiterung kann deaktiviert sein. ftp_*-Funktionen erfordern PHP, das mit --enable-ftp kompiliert wurde (oder das php-ftp-Paket). Schützen Sie sich mit if (!function_exists('ftp_connect')) { ... }, wenn Portabilität wichtig ist.
• Passiver Modus. Wenn ftp_connect() und ftp_login() erfolgreich sind, aber Verzeichnislistings oder Übertragungen hängen, liegt der Server wahrscheinlich hinter einer Firewall — wechseln Sie nach dem Anmelden mit ftp_pasv($conn, true) in den passiven Modus.
• Verbinden ist nicht Authentifizieren. Ein zurückgegebenes Handle bedeutet nur, dass der TCP-Kanal geöffnet ist. Ein falsches Passwort schlägt später bei ftp_login() fehl.
• Kein ftp://-Präfix. Übergeben Sie einen einfachen Hostnamen; das Schema wird durch die Funktion impliziert.

Einen Überblick über das gesamte FTP-Toolkit finden Sie in der Referenz zu den PHP-FTP-Funktionen.

Practice