fpassthru()

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

La fonction fpassthru() est une fonction PHP intégrée qui lit toutes les données restantes à partir d'un pointeur de fichier ouvert — en commençant à la position actuelle du pointeur et en continuant jusqu'à la fin du fichier (EOF) — et les écrit directement dans le flux de sortie (ce que le navigateur ou le terminal reçoit). Comme elle transmet les données par blocs au lieu de charger l'intégralité du fichier dans une chaîne, elle est particulièrement adaptée à l'envoi de fichiers volumineux sans épuiser la limite mémoire de PHP.

Cette page couvre la syntaxe de la fonction, un modèle d'utilisation étape par étape, un exemple concret de téléchargement de fichier, ses différences avec readfile(), et les points d'attention à connaître.

Elle retourne le nombre d'octets écrits dans la sortie en cas de succès, ou false en cas d'échec.

Voici la syntaxe de base de la fonction fpassthru() :

La syntaxe PHP de fpassthru()

fpassthru(resource $stream): int|false

Où $stream est un pointeur de fichier qui doit être valide et déjà ouvert (généralement la valeur de retour de fopen()). Après le retour de fpassthru(), le pointeur est à EOF et les données ont été consommées — vous ne pouvez pas les relire sans revenir en arrière.

Comment utiliser la fonction fpassthru() ?

L'utilisation de la fonction fpassthru() est simple. Voici les étapes à suivre :

1. Ouvrez le fichier avec fopen() et assurez-vous que le pointeur de fichier est à la position de départ souhaitée.
2. Appelez fpassthru() avec le pointeur de fichier. Elle lira jusqu'à EOF et écrira dans le flux de sortie.
3. Vérifiez la valeur de retour pour confirmer le succès, puis fermez le fichier avec fclose().

Voici un exemple de code qui illustre l'utilisation de la fonction fpassthru() :

Comment utiliser la fonction fpassthru() ?

<?php

$filename = 'largefile.txt';
$file = fopen($filename, 'r');
if ($file) {
   if (fpassthru($file) === false) {
      echo "Error reading file!";
   }
   fclose($file);
} else {
   echo "Unable to open file!";
}

Dans cet exemple, nous ouvrons le fichier largefile.txt en utilisant la fonction fopen() en mode lecture seule. Nous vérifions si le fichier a été ouvert avec succès à l'aide d'une instruction if et, si c'est le cas, nous envoyons son contenu vers le flux de sortie standard avec fpassthru(). Nous vérifions la valeur de retour pour gérer les éventuelles erreurs de lecture, puis fermons le descripteur avec fclose().

Remarque sur la mise en tampon de sortie : Si la mise en tampon de sortie PHP est active (par exemple via ob_start()), fpassthru() écrira directement dans le tampon de sortie courant au lieu d'envoyer immédiatement les données au navigateur.

Lecture à partir de la position actuelle, pas depuis le début du fichier

Un détail important est que fpassthru() commence à la position actuelle du pointeur. Si vous avez déjà lu une partie du fichier (par exemple avec fgets() ou fread()), seuls les octets restants sont envoyés. Cela vous permet de lire un en-tête vous-même et de diffuser le reste :

<?php

$file = fopen('php://temp', 'r+');
fwrite($file, "HEADER\nbody-line-1\nbody-line-2\n");
rewind($file);

// Consume the first line manually.
echo "First line: " . fgets($file);

// Stream everything left after the pointer.
fpassthru($file);
fclose($file);

Cela affiche :

First line: HEADER
body-line-1
body-line-2

La ligne HEADER n'est pas répétée, car le pointeur l'avait déjà dépassée lorsque fpassthru() s'est exécutée.

Envoyer un fichier en téléchargement

L'utilisation la plus courante en production de fpassthru() consiste à diffuser un fichier vers le navigateur en téléchargement. Définissez les en-têtes appropriés, ouvrez le fichier en mode binaire ('rb'), et laissez fpassthru() transmettre les octets :

<?php

$path = '/var/www/files/report.pdf';

if (is_readable($path)) {
   header('Content-Type: application/pdf');
   header('Content-Disposition: attachment; filename="report.pdf"');
   header('Content-Length: ' . filesize($path));

   $file = fopen($path, 'rb');
   fpassthru($file);
   fclose($file);
   exit;
}

http_response_code(404);
echo 'File not found.';

Le mode 'rb' est important sous Windows, où le mode texte par défaut pourrait corrompre les données binaires telles que les images, les PDF ou les archives. Sous Linux et macOS, le drapeau b est sans effet, il est donc recommandé de toujours l'inclure pour les téléchargements.

fpassthru() vs. readfile()

Les deux fonctions diffusent un fichier vers la sortie, mais elles opèrent à des niveaux différents :

Si vous souhaitez simplement envoyer l'intégralité d'un fichier sans descripteur ouvert, readfile() est plus concis. Utilisez fpassthru() lorsque vous disposez déjà d'un pointeur de fichier ou que vous devez ignorer une partie du flux en premier.

Conclusion

La fonction fpassthru() est un outil utile en PHP pour lire des fichiers volumineux sans les charger en mémoire. En suivant les étapes décrites dans ce guide, vous pouvez facilement utiliser la fonction fpassthru() dans vos projets PHP pour lire le contenu des fichiers à partir de la position actuelle du pointeur et l'envoyer vers le flux de sortie standard.

Pratique