file_put_contents()

La fonction file_put_contents() écrit une chaîne dans un fichier en un seul appel. C'est le remplaçant moderne et en une ligne de la séquence classique fopen() → fwrite() → fclose() : PHP ouvre le fichier, écrit les données et ferme le descripteur pour vous. Cette page couvre sa syntaxe, ses paramètres, sa valeur de retour, les flags d'ajout et de verrouillage, ainsi que les erreurs les plus fréquentes.

Syntaxe

file_put_contents(string $filename, mixed $data, int $flags = 0, ?resource $context = null): int|false

Paramètres

Valeur de retour

file_put_contents() retourne le nombre d'octets écrits, ou false en cas d'échec. Étant donné que 0 est un résultat valide (falsy) lorsque vous écrivez une chaîne vide, vérifiez toujours l'échec avec la comparaison stricte === false plutôt qu'un test de véracité non strict.

Écriture dans un fichier

Par défaut, la fonction écrase le contenu existant du fichier (ou crée le fichier s'il est absent) :

<?php

$filename = 'myfile.txt';
$data     = 'This is some data to be written to the file.';

$bytes = file_put_contents($filename, $data);

if ($bytes === false) {
    echo "Failed to write to $filename";
} else {
    echo "Wrote $bytes bytes to $filename";
}

Sortie :

Wrote 44 bytes to myfile.txt

Le compteur retourné, 44, est la longueur de la chaîne en octets.

Ajout au lieu d'écrasement

Passez le flag FILE_APPEND pour ajouter à la fin du fichier plutôt que de remplacer son contenu — pratique pour les fichiers journaux :

<?php

$log = 'app.log';

file_put_contents($log, "First line\n", FILE_APPEND);
file_put_contents($log, "Second line\n", FILE_APPEND);

echo file_get_contents($log);

Sortie :

First line
Second line

Sans FILE_APPEND, le second appel effacerait la première ligne.

Verrouillage du fichier lors de l'écriture

Si plusieurs processus peuvent écrire simultanément dans le même fichier, ajoutez LOCK_EX pour acquérir un verrou exclusif pendant toute la durée de l'écriture. Combinez les flags avec l'opérateur OR bit à bit (|) :

<?php

file_put_contents('counter.txt', "ping\n", FILE_APPEND | LOCK_EX);

Cela empêche deux processus d'entrelacer leurs sorties et de corrompre le fichier.

Écriture d'un array

Lorsque $data est un array, ses éléments string sont concaténés sans séparateur. Collez-les vous-même si vous avez besoin de délimiteurs :

<?php

$lines = ['apple', 'banana', 'cherry'];

file_put_contents('fruits.txt', implode("\n", $lines));

echo file_get_contents('fruits.txt');

Sortie :

apple
banana
cherry

Erreurs fréquentes

• Échec silencieux sur les permissions. Si le répertoire n'est pas accessible en écriture, l'appel retourne false et émet un avertissement — il ne lève pas d'exception. Vérifiez la valeur de retour (=== false) ou encapsulez l'appel et inspectez error_get_last().
• Le répertoire parent doit exister. file_put_contents() crée le fichier mais pas les répertoires manquants. Appelez mkdir($dir, 0777, true) au préalable si nécessaire.
• FILE_APPEND n'est pas la même chose que l'écrasement. Oublier le flag est la cause la plus fréquente du problème « mon journal continue d'être vidé ».
• Les données vides sont valides. Écrire '' retourne 0, qui est falsy — utilisez === false pour ne pas confondre une écriture vide réussie avec une erreur.

Fonctions associées

• file_get_contents() — le pendant en lecture qui charge tout un fichier dans une string.
• fwrite() — écriture bas niveau quand vous avez besoin d'un descripteur ouvert (par ex. nombreuses petites écritures dans une boucle).
• fopen() — ouvre un descripteur de fichier pour une lecture ou une écriture en flux.
• file_exists() — vérifie si un fichier est présent avant d'écrire.

Conclusion

file_put_contents() est la façon la plus simple d'écrire une string dans un fichier en PHP : un seul appel ouvre, écrit et ferme le fichier. Utilisez FILE_APPEND pour ajouter à un fichier, LOCK_EX pour les écrivains concurrents, et vérifiez toujours le succès avec un test strict === false.

Pratique