ftell()

Qu'est-ce que la fonction ftell() ?

La fonction ftell() est une fonction PHP intégrée qui retourne la position actuelle du pointeur de fichier — le décalage en octets, compté depuis le début du fichier, à partir duquel la prochaine lecture ou écriture aura lieu. Chaque handle de fichier ouvert maintient un curseur interne ; fread(), fwrite() et fgets() le font avancer, tandis que fseek() et rewind() le déplacent explicitement. ftell() indique simplement où se trouve ce curseur sans le modifier.

Connaître le décalage est utile lorsque vous avez besoin d'enregistrer votre position dans un fichier (pour pouvoir reprendre plus tard avec fseek()), mesurer le nombre d'octets consommés jusqu'à présent, ou détecter la fin d'un enregistrement dans un fichier à largeur fixe ou binaire.

Cette page couvre la syntaxe, un exemple exécutable, la valeur retournée par ftell(), les pièges courants (mode ajout, flux), et sa relation avec les autres fonctions de pointeur de fichier.

Syntaxe

ftell(resource $stream): int|false

$stream doit être un pointeur de fichier retourné par fopen() (ou une fonction comme fsockopen()). La fonction retourne la position sous la forme d'un décalage entier en octets, ou false en cas d'échec — par exemple si le flux n'est pas positionnable. Puisque 0 (le début du fichier) est un résultat valide mais « falsy », testez toujours la valeur de retour avec === :

$pos = ftell($file);
if ($pos === false) {
    // could not determine the position
}

Comment utiliser la fonction ftell()

Le flux habituel est le suivant :

1. Ouvrez le fichier avec fopen() dans le mode dont vous avez besoin.
2. Lisez ou écrivez dans le fichier pour que le pointeur se déplace.
3. Appelez ftell() avec le pointeur de fichier pour lire sa position.
4. Utilisez ce décalage — par exemple, stockez-le ou passez-le à fseek().
5. Fermez le fichier avec fclose().

L'exemple ci-dessous est entièrement autonome : il crée d'abord un fichier temporaire, vous pouvez donc l'exécuter tel quel sans préparer de données.

<?php

// Create a temporary file with known contents.
$filename = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($filename, 'Hello, World! This is a test.');

$file = fopen($filename, 'r');

echo "Start position: " . ftell($file) . "\n";   // 0

fread($file, 5);                                  // read "Hello"
echo "After reading 5 bytes: " . ftell($file) . "\n";  // 5

fread($file, 5);                                  // read ", Wor"
echo "After reading 5 more: " . ftell($file) . "\n";   // 10

rewind($file);                                    // jump back to the start
echo "After rewind: " . ftell($file) . "\n";      // 0

fseek($file, 7);                                  // jump to byte 7
echo "After fseek to 7: " . ftell($file) . "\n";  // 7
echo "Next 5 bytes: " . fread($file, 5) . "\n";   // "World"

fclose($file);
unlink($filename);

Sortie :

Start position: 0
After reading 5 bytes: 5
After reading 5 more: 10
After rewind: 0
After fseek to 7: 7
Next 5 bytes: World

Chaque appel à fread() fait avancer le pointeur du nombre d'octets effectivement lus, donc ftell() passe de 0 à 5 puis à 10. rewind() le remet à 0, et fseek($file, 7) le déplace directement à l'octet 7, où commence le mot World.

Mode ajout : un piège courant

Lorsqu'un fichier est ouvert en mode ajout ('a' ou 'a+'), chaque écriture va à la fin du fichier, quelle que soit la position du pointeur. ftell() peut indiquer 0 juste après l'ouverture même si les écritures se font à la fin — sa valeur de retour ne décrit pas de manière fiable l'endroit où la prochaine écriture aura lieu en mode ajout. Si vous avez besoin de positions précises, ouvrez le fichier avec 'r+', 'w+' ou 'c+' et déplacez-vous explicitement avec fseek().

De même, les flux non positionnables (comme certains flux réseau ou de type pipe) ne peuvent pas fournir une position significative et ftell() retourne false pour eux.

Fonctions associées

ftell() fonctionne rarement seule. Elle fait partie d'une petite famille de fonctions de pointeur de fichier :

• fopen() — ouvrir un fichier et obtenir le pointeur que ftell() lit.
• fread() — lire des octets et faire avancer le pointeur.
• fwrite() — écrire des octets et faire avancer le pointeur.
• fseek() — déplacer le pointeur vers une position absolue ou relative ; associez-la à ftell() pour sauvegarder et restaurer des décalages.
• rewind() — réinitialiser le pointeur au début (équivalent à fseek($file, 0)).
• fclose() — fermer le fichier lorsque vous avez terminé.

Pour une vue d'ensemble plus large, consultez Gestion des fichiers PHP.

Conclusion

La fonction ftell() indique le décalage en octets actuel d'un pointeur de fichier sans le déplacer, ce qui en fait le complément naturel de fseek() et rewind() pour naviguer dans les fichiers. N'oubliez pas de comparer son résultat avec === false (car 0 est un décalage valide), et gardez à l'esprit que le mode ajout et les flux non positionnables ne retournent pas de positions fiables.

Pratique