Comprendre la fonction PHP ftp_alloc()

L'extension FTP de PHP vous permet de déplacer des fichiers entre votre script et un serveur distant. La fonction ftp_alloc() est le signal de courtoisie que vous envoyez avant un téléversement : elle demande au serveur de réserver de l'espace disque pour un fichier que vous êtes sur le point de transférer. Cette page explique ce que fait réellement ftp_alloc(), sa syntaxe et ses paramètres, pourquoi la plupart des téléversements n'en ont pas besoin, et comment interpréter le message de diagnostic qu'elle retourne.

Ce que fait ftp_alloc()

ftp_alloc() envoie la commande FTP ALLO (allocate) au serveur connecté, en demandant qu'il réserve un nombre donné d'octets pour un fichier que vous avez l'intention de téléverser. Elle ne crée pas le fichier, n'écrit aucune donnée et ne transfère rien — elle se contente de demander au serveur s'il peut accueillir un fichier de cette taille.

Le revers de la médaille : la commande ALLO est optionnelle dans le protocole FTP, et la grande majorité des serveurs FTP modernes l'ignorent et retournent simplement un succès quelle que soit l'espace libre. Elle n'avait d'importance que pour les systèmes anciens (mainframes, systèmes de fichiers à enregistrements orientés) qui devaient pré-réserver le stockage avant une écriture. Pour cette raison, un résultat true ne garantit pas que l'appel ultérieur à ftp_put() réussira, et vous devriez traiter ftp_alloc() comme une vérification indicative plutôt que comme une véritable garantie d'espace disque.

Syntaxe

ftp_alloc(FTP\Connection $ftp, int $size, string &$response = null): bool

Valeur de retour : true en cas de succès, false en cas d'échec. Depuis PHP 8.1, l'argument $ftp est un objet FTP\Connection plutôt qu'une ressource, mais l'utilisation reste inchangée.

Comment utiliser ftp_alloc()

Vous devez vous connecter et vous authentifier avant d'appeler ftp_alloc(). Le flux habituel est : connexion, authentification, passage en mode passif, puis allocation.

<?php

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

$size = 1024; // bytes you intend to upload

// $response captures the server's reply by reference
if (ftp_alloc($ftp, $size, $response)) {
    echo "Allocated $size bytes. Server said: $response\n";
} else {
    echo "Allocation failed: $response\n";
}

ftp_close($ftp);

ftp_connect() ouvre la connexion, ftp_login() effectue l'authentification, et ftp_pasv() place la session en mode passif (plus sûr derrière les pare-feux et le NAT). Le troisième argument de ftp_alloc() — $response — est renseigné par référence avec le message brut du serveur, ce qui vous permet de journaliser exactement pourquoi une allocation a été refusée. Enfin, ftp_close() libère la connexion.

Un schéma pratique : vérifier avant de téléverser

ftp_alloc() est plus utile en tant que garde-fou avant un vrai téléversement, pour échouer tôt sur les serveurs qui respectent effectivement ALLO :

<?php

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

$localFile  = 'report.pdf';
$remoteFile = 'uploads/report.pdf';
$size       = filesize($localFile); // bytes the upload will need

if (!ftp_alloc($ftp, $size, $response)) {
    echo "Server refused to reserve {$size} bytes: $response\n";
} elseif (ftp_put($ftp, $remoteFile, $localFile, FTP_BINARY)) {
    echo "Uploaded $localFile to $remoteFile\n";
} else {
    echo "Upload failed even though allocation succeeded.\n";
}

ftp_close($ftp);

Ici, filesize() fournit le nombre exact d'octets, ftp_alloc() effectue la vérification indicative, et ftp_put() réalise le transfert réel en mode binaire.

Pièges courants

• La plupart des serveurs ignorent ALLO. Un retour true signifie souvent « commande acceptée », pas « espace vérifié ». Gérez toujours une éventuelle erreur de téléversement par la suite.
• Elle ne crée ni ne téléverse un fichier. Utilisez ftp_put() ou ftp_fput() pour le transfert effectif.
• Passez $size en octets. Pour un vrai téléversement, déduisez-le de filesize() plutôt que de le deviner.
• Lisez $response. Comme il est renseigné par référence, c'est votre seule fenêtre sur pourquoi le serveur a refusé — journalisez-le.
• Elle ne vous indiquera pas la taille d'un fichier distant. Pour cela, utilisez ftp_size().

Conclusion

ftp_alloc() envoie une requête FTP ALLO pour réserver de l'espace en vue d'un prochain téléversement, et signale la réponse du serveur via un paramètre passé par référence. En pratique, c'est une étape indicative que la plupart des serveurs modernes ignorent ; associez-la donc à une gestion d'erreur appropriée autour de votre appel réel à ftp_put(). Pour en savoir plus sur les fonctions PHP en général, consultez le chapitre fonctions PHP.

Entraînez-vous