fscanf()

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

La fonction fscanf() lit depuis un fichier ouvert et analyse son contenu selon une chaîne de format de style printf. Au lieu de vous donner une ligne de texte brute comme le fait fgets(), fscanf() divise l'entrée en champs typés — string, entiers, flottants — en une seule étape. C'est l'outil PHP de prédilection quand un fichier suit une mise en page fixe par colonnes et que vous souhaitez que chaque valeur soit déjà convertie au bon type.

Cette page couvre la syntaxe, les spécificateurs de format disponibles, les deux façons dont fscanf() peut retourner ses résultats, les erreurs les plus courantes, et comment elle se compare aux fonctions apparentées.

Syntaxe

fscanf(resource $stream, string $format, mixed &...$vars): array|int|false

La valeur de retour dépend de la façon dont vous l'appelez :

• Avec des arguments de variables supplémentaires → retourne le nombre de champs correctement assignés, ou false en fin de fichier.
• Sans variables supplémentaires → retourne un array des champs analysés au lieu d'écrire dans des variables.

fscanf() avance le pointeur de fichier au-delà de ce qu'il a consommé, ainsi des appels répétés parcourent le fichier jeton par jeton.

Spécificateurs de format

La chaîne de format est au cœur de fscanf(). Les spécificateurs les plus courants sont :

Les espaces blancs dans la chaîne de format correspondent à toute suite d'espaces blancs (espaces, tabulations, sauts de ligne) dans l'entrée, c'est pourquoi %s est délimité par des espaces blancs plutôt que par des fins de ligne.

Lecture d'un fichier avec des variables

Le modèle typique est : ouvrir le fichier, boucler tant que fscanf() retourne le nombre de champs attendu, puis le fermer. Supposons que data.txt contienne un enregistrement par ligne :

John Smith 30 50000.5
Jane Doe 28 62000

Vous pouvez analyser chaque ligne dans des variables typées comme suit :

<?php
$file = fopen('data.txt', 'r');

if ($file === false) {
    die("Error: Could not open file.");
}

while (fscanf($file, "%s %s %d %f", $first, $last, $age, $salary) === 4) {
    echo "Name: $first $last, Age: $age, Salary: $salary\n";
}

fclose($file);
?>

Résultat :

Name: John Smith, Age: 30, Salary: 50000.5
Name: Jane Doe, Age: 28, Salary: 62000

Comparer la valeur de retour à 4 (le nombre de champs attendus par le format) est la clé d'une boucle sûre : en fin de fichier fscanf() retourne false, et sur une ligne mal formée elle retourne un nombre inférieur, ainsi la boucle s'arrête proprement au lieu de tourner indéfiniment.

Lecture d'un fichier dans un array

Si vous omettez les arguments de variables, fscanf() retourne chaque enregistrement analysé sous forme d'array. C'est pratique quand vous souhaitez collecter des lignes plutôt que de les traiter variable par variable :

<?php
$file = fopen('data.txt', 'r');

while ($row = fscanf($file, "%s %s %d %f")) {
    // $row is [first, last, age, salary]
    [$first, $last, $age, $salary] = $row;
    echo "$last, $first earns $salary\n";
}

fclose($file);
?>

Résultat :

Smith, John earns 50000.5
Doe, Jane earns 62000

fscanf() vs. sscanf()

fscanf() lit depuis un pointeur de fichier ; sscanf() effectue exactement la même analyse mais sur une string que vous avez déjà en mémoire. Si vos données se trouvent dans une variable plutôt que dans un fichier, utilisez sscanf() :

<?php
$count = sscanf("2024-06-21", "%d-%d-%d", $year, $month, $day);
echo "$count fields parsed: $year / $month / $day\n";
?>

Résultat :

3 fields parsed: 2024 / 6 / 21

Erreurs courantes

• %s s'arrête aux espaces blancs, pas à la fin de ligne. Un nom comme New York est lu comme deux champs %s, pas un seul. Adaptez le format à la structure réelle de vos données.
• Vérifiez toujours la valeur de retour. Boucler sur le nombre de champs (=== 4) — et non sur !feof() — vous protège des lignes incomplètes et des boucles infinies.
• Vérifiez fopen() en premier. fscanf() a besoin d'une ressource valide ; une ouverture échouée retourne false.
• Pour les données séparées par des virgules, préférez fgetcsv(). fscanf() est conçu pour les colonnes délimitées par des espaces blancs à format fixe, pas pour les champs CSV entre guillemets.

Fonctions associées

• sscanf() — analyser une string formatée au lieu d'un fichier.
• fgetcsv() — lire et diviser des lignes CSV.
• fgets() — lire une ligne de texte brute.
• fopen() / fclose() — ouvrir et fermer le flux de fichier.

Conclusion

fscanf() convertit le contenu de fichier délimité par des espaces blancs en valeurs PHP typées en un seul appel. Choisissez la forme avec variables quand vous traitez les enregistrements un à la fois, ou la forme array quand vous les collectez. Validez toujours la valeur de retour pour piloter votre boucle, et passez à sscanf() pour les string en mémoire ou à fgetcsv() pour les vrais fichiers CSV.

Pratique