__halt_compiler()

Dans cet article, nous allons nous concentrer sur la construction de langage PHP __halt_compiler(). Nous vous fournirons une vue d'ensemble de la construction, de son fonctionnement et des exemples de son utilisation.

Introduction à la construction __halt_compiler()

La construction de langage __halt_compiler() est une fonctionnalité unique et puissante de PHP. Elle vous permet d'intégrer des données directement dans votre code PHP. Ces données peuvent être de n'importe quel type, notamment du texte, des données binaires, ou même un script complet.

Lorsque l'interpréteur PHP rencontre la construction __halt_compiler() dans votre code, il interrompt le parseur PHP et traite tout ce qui suit l'appel comme des données brutes. Cela signifie que vous pouvez intégrer n'importe quel type de données dans votre code et y accéder ultérieurement sous forme de chaîne ou de données binaires.

__halt_compiler() est une construction de langage, et non une fonction ordinaire : vous l'appelez sans arguments et elle ne retourne aucune valeur. Elle est le plus souvent utilisée pour créer des outils en fichier unique où le code et les données sont regroupés — par exemple des archives auto-extractibles (le format PHAR de PHP utilise exactement cette technique) ou des installeurs qui embarquent leur propre contenu.

Comment utiliser la construction __halt_compiler()

La construction __halt_compiler() est très facile à utiliser. Il suffit de l'appeler dans votre code PHP, suivi des données que vous souhaitez intégrer. Voici un exemple :

Comment utiliser la construction __halt_compiler() ?

Dans cet exemple, nous avons un script PHP simple qui affiche du texte à l'aide de la construction echo. Nous appelons ensuite la construction __halt_compiler() et intégrons des données brutes après celle-ci. Lorsque l'interpréteur PHP rencontre la construction __halt_compiler(), il interrompt le parseur et traite tout ce qui suit comme des données brutes.

Accéder aux données intégrées avec __COMPILER_HALT_OFFSET__

Lorsqu'un fichier contient __halt_compiler(), PHP définit une constante spéciale, __COMPILER_HALT_OFFSET__, qui contient la position en octets du premier caractère après l'appel. C'est la méthode canonique et la plus rapide pour lire le contenu intégré depuis le même fichier — vous n'avez pas à rechercher vous-même un marqueur dans le fichier.

Lecture des données intégrées depuis le même fichier

<?php
// File: bundle.php
echo "Reading the embedded payload...\n";

// Open this very file and jump straight to the data.
$fp = fopen(__FILE__, 'rb');
fseek($fp, __COMPILER_HALT_OFFSET__);
$data = stream_get_contents($fp);
fclose($fp);

echo $data;

__halt_compiler();
Hello from the embedded data!

Ici, __COMPILER_HALT_OFFSET__ pointe vers l'octet situé juste après __halt_compiler();, nous y positionnons donc le curseur et lisons tout ce qui suit en tant que contenu brut. La constante n'existe que dans un fichier qui contient effectivement la construction.

Accéder aux données intégrées depuis un autre fichier

Si vous devez lire le contenu depuis un autre fichier, la constante __COMPILER_HALT_OFFSET__ de ce fichier n'est pas disponible, vous devez donc localiser le marqueur manuellement avec strpos() et extraire les données avec substr() après les avoir chargées via file_get_contents().

Voici un exemple de lecture des données intégrées depuis un script séparé :

Accéder aux données intégrées en PHP

<?php
// File: embed.php
echo "This is some PHP code.";
__halt_compiler();
This is some raw data.
?>

<?php
// File: extract.php
// Read the script file and extract the data
$content = file_get_contents('embed.php');
$pos = strpos($content, '__halt_compiler();');
if ($pos !== false) {
    $offset = $pos + strlen('__halt_compiler();');
    $data = substr($content, $offset);
    echo $data;
}
?>

Dans cet exemple, nous créons d'abord un fichier avec des données intégrées. Nous utilisons ensuite un script séparé pour lire le fichier original et extraire les données en localisant le marqueur __halt_compiler(); et en calculant le décalage. Enfin, nous affichons les données extraites à l'aide de la construction echo.

Remarque : La constante __COMPILER_HALT_OFFSET__ n'est définie qu'à l'intérieur du fichier qui contient effectivement __halt_compiler(). Lors de la lecture d'un autre fichier, strpos() retourne false si le marqueur est absent, vérifiez donc toujours la position avec un test !== false avant de calculer le décalage.

Restrictions et points d'attention

Gardez ces règles à l'esprit lorsque vous utilisez __halt_compiler() :

• Elle doit être appelée au niveau supérieur d'un fichier. Vous ne pouvez pas la placer à l'intérieur d'une fonction, d'une méthode, d'une condition, d'une boucle ou de tout autre bloc. Faire cela provoque une erreur fatale.
• Une seule occurrence par fichier. Un fichier ne peut contenir __halt_compiler() qu'une seule fois — elle marque un unique point de coupure.
• Tout ce qui suit est ignoré en tant que code. La balise fermante ?> (si elle est présente) et tout ce qui vient après l'appel sont traités comme des octets bruts, jamais parsés. C'est pourquoi on omet généralement le ?> final et on laisse simplement les données suivre.
• Ce n'est pas une fonction. Vous ne pouvez pas en prendre l'adresse, la passer comme rappel, ou l'appeler dynamiquement.

Conclusion

En conclusion, la construction de langage __halt_compiler() est une fonctionnalité puissante et flexible de PHP qui vous permet d'intégrer des données directement dans votre code. En comprenant comment fonctionne la construction et comment accéder aux données intégrées, vous pouvez tirer parti de cette fonctionnalité pour créer des scripts PHP plus puissants et flexibles. Les cas d'utilisation pratiques courants incluent les archives auto-extractibles, le regroupement de ressources statiques (comme CSS ou JavaScript) avec de la logique PHP, et la création d'applications PHP en fichier unique. Si vous avez principalement besoin d'importer du code depuis d'autres fichiers plutôt que d'intégrer des données brutes, consultez include à la place.

Practice