ftp_site()

Comprendre la fonction PHP ftp_site()

La fonction ftp_site() est une fonction PHP intégrée qui envoie une commande SITE à un serveur FTP. SITE est une commande FTP générique destinée aux instructions qui sortent du protocole FTP standard — des actions que chaque fournisseur de serveur implémente à sa façon, comme la modification des permissions de fichiers, le réglage des délais d'inactivité ou l'exécution de tâches de maintenance spécifiques au serveur.

Comme la signification d'une commande SITE est entièrement définie par le serveur distant, ftp_site() est la solution de secours à laquelle on recourt lorsqu'aucune fonction PHP FTP dédiée n'existe pour ce dont on a besoin. Cet article explique ce que fait la fonction, quand l'utiliser (et quand ne pas l'utiliser), et comment traiter son résultat en toute sécurité.

Pour l'utiliser, vous devez d'abord ouvrir une connexion avec ftp_connect() et vous authentifier avec ftp_login(). Consultez la vue d'ensemble PHP FTP pour découvrir la famille complète de fonctions.

Qu'est-ce que ftp_site() ?

La fonction prend deux paramètres :

1. ftp — La connexion FTP retournée par ftp_connect() (ou ftp_ssl_connect()).
2. command — La chaîne de commande SITE brute à envoyer, sans le mot-clé SITE en tête (PHP l'ajoute pour vous).

Elle retourne true si le serveur a accepté la commande et false en cas d'échec. Un résultat true signifie uniquement que le serveur a accepté la commande — cela ne garantit pas que l'action sous-jacente (par exemple, le changement de permission) a réussi, car le comportement de SITE est défini par le serveur.

Syntaxe de ftp_site()

La syntaxe de la fonction ftp_site() est la suivante :

Syntaxe de ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

À partir de PHP 8.1, le premier argument est un objet FTP\Connection (dans les versions antérieures, c'était une ressource). L'argument command est l'instruction SITE à envoyer — par exemple CHMOD 644 file.txt. Vous ne passez que la partie après SITE ; PHP ajoute automatiquement le mot-clé en préfixe.

Utilisation de ftp_site()

Pour utiliser la fonction ftp_site(), vous devez d'abord établir une connexion au serveur FTP à l'aide de la fonction ftp_connect(). Voici un exemple :

Utilisation de ftp_site()

<?php

// Set up an FTP connection
$conn = @ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

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

Dans cet exemple, nous nous connectons avec ftp_connect(), nous nous authentifions avec ftp_login(), nous envoyons SITE CHMOD 755 pour modifier les permissions de index.php, et enfin nous fermons la connexion avec ftp_close().

Remarque : Les commandes SITE sont spécifiques au serveur. SITE CHMOD n'est pas universellement pris en charge par tous les serveurs FTP. Pour les modifications standard de permissions de fichiers, préférez la fonction dédiée ftp_chmod(), qui est portable et retourne la nouvelle valeur de permission. Utilisez ftp_site() uniquement pour les actions qui n'ont pas de fonction FTP dédiée.

Commandes SITE courantes

L'ensemble exact des commandes prises en charge dépend du logiciel serveur (ProFTPD, vsftpd, Pure-FTPd, etc.), mais quelques-unes sont largement disponibles :

En cas de doute, exécutez SITE HELP pour découvrir ce qu'un serveur particulier accepte :

Découvrir les commandes SITE prises en charge

<?php

$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Gestion des erreurs dans ftp_site()

Il est important de gérer correctement les erreurs lors de l'utilisation de la fonction ftp_site(). Si la fonction retourne false, cela signifie que l'opération a échoué. Voici un exemple de gestion des erreurs :

Gestion des erreurs dans ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

En vérifiant la valeur de retour, vous évitez de continuer silencieusement après une commande rejetée par le serveur. Notez que ftp_site() retourne false à la fois lorsque la connexion est défectueuse et lorsque le serveur ne reconnaît simplement pas la commande — un résultat false vous indique donc qu'il faut basculer vers une fonction dédiée ou une approche différente.

ftp_site() par rapport à ftp_raw() et ftp_exec()

ftp_site() est étroitement liée à deux autres fonctions "envoyer une instruction brute", et il est utile de savoir laquelle choisir :

• ftp_site() — envoie une seule commande SITE et retourne un boolean. À utiliser pour les actions spécifiques au serveur comme CHMOD ou UMASK.
• ftp_raw() — envoie n'importe quelle commande FTP brute (pas seulement SITE) et retourne la réponse complète du serveur sous forme d'array, vous permettant de lire vous-même le code de statut. À utiliser lorsque vous avez besoin d'inspecter la réponse.
• ftp_exec() — exécute un programme sur le serveur via SITE EXEC, lorsque pris en charge. À utiliser uniquement sur des serveurs que vous contrôlez et en lesquels vous avez confiance.

Pour les opérations courantes (téléversement, téléchargement, listage, renommage), préférez les fonctions dédiées décrites dans la vue d'ensemble PHP FTP ; elles sont plus portables que les commandes SITE construites manuellement.

Conclusion

La fonction ftp_site() vous permet d'envoyer des commandes SITE spécifiques au serveur lorsqu'aucune fonction PHP FTP dédiée ne convient. Vérifiez toujours sa valeur de retour, rappelez-vous qu'un envoi réussi n'est pas la même chose qu'une action réussie, et préférez les fonctions portables comme ftp_chmod() chaque fois que l'une d'elles existe.

Pratique