Les origines et l’utilité du Heredoc en PHP

par lena · 18 août 2024

Créer du contenu dynamique en PHP nécessite souvent une confection sur mesure. La syntaxe Heredoc facilite cette tâche en éliminant les complexités de syntaxe avec fluidité et élégance.

Le développement web avec PHP implique la génération de divers types de contenu, comme HTML, CSS et JavaScript, souvent en intégrant des variables PHP. Avant l’introduction de Heredoc, les développeurs devaient gérer la concaténation et les guillemets pour assembler ce contenu, ce qui compliquait la lecture et la maintenance du code. Pour répondre à ce besoin, la syntaxe Heredoc a été introduite dans PHP (strings), inspirée par des langages comme Perl et C.

Le principal objectif de Heredoc est de simplifier l’écriture et la lecture des chaînes multi-lignes tout en permettant l’interpolation de variables sans avoir à gérer les guillemets ou la concaténation. Avant l’introduction de cette fonctionnalité, les développeurs devaient souvent jongler avec des guillemets et des points (.) pour assembler du texte et des variables, ce qui augmentait les risques d’erreurs syntaxiques.

Voyons maintenant un exemple concret de génération de contenu HTML en PHP, en comparant une méthode sans Heredoc et une méthode avec Heredoc, pour mieux illustrer la souplesse qu’apporte cette syntaxe.

Sans Heredoc :

function generateSpotsList($spot, $index) {
    $imageUrl = "/wp-content/plugins/pem-carto/icons/" . $spot->SPOT_SUBTYPE_ICON;
    return "<li class='spot_marker " . $spot->SPOT_SUBTYPE_SLUG . "' data-lat='" . $spot->SPOT_LAT . "' data-lon='" . $spot->SPOT_LON . "' data-marker='$index'>" .
           "<img src='$imageUrl' alt='" . $spot->SPOT_SUBTYPE_LABEL . "' style='width: 14px; height: 14px;'> - " .
           $spot->SPOT_INDEX . " - " . $spot->SPOT_LABEL . 
           "</li>";
}

Cette approche montre bien la difficulté à lire et à maintenir un code mélangeant HTML et PHP. Les guillemets et la concaténation (.) rendent le code confus, notamment lorsque vous devez manipuler plusieurs variables et insérer du contenu dynamique.

Avec Heredoc :

function generateSpotsList($spot, $index) {
    $imageUrl = "/wp-content/plugins/pem-carto/icons/{$spot->SPOT_SUBTYPE_ICON}";
    
    return <<<HTML
    <li class="spot_marker {$spot->SPOT_SUBTYPE_SLUG}" data-lat="{$spot->SPOT_LAT}" data-lon="{$spot->SPOT_LON}" data-marker="$index">
        <img src="$imageUrl" alt="{$spot->SPOT_SUBTYPE_LABEL}" style="width: 14px; height: 14px;"> - 
        {$spot->SPOT_INDEX} - {$spot->SPOT_LABEL}
    </li>
    HTML;
}

Avec Heredoc, l’ensemble du code est plus lisible, plus facile à écrire et à maintenir. Le principal avantage est la possibilité d’insérer des variables directement dans le texte sans avoir à jongler avec la concaténation et les guillemets.

Mode d’emploi du Heredoc : Syntaxe et utilisation

Après avoir vu un exemple d’utilisation avec du HTML, il est important de comprendre la syntaxe et le mode d’emploi de Heredoc. Cette fonctionnalité est très flexible et peut être utilisée pour bien d’autres types de contenu que du HTML, comme du CSS, du JavaScript ou même du texte brut.

La syntaxe de Heredoc est simple : elle commence par <<< suivi d’un identifiant, puis le contenu est écrit sur plusieurs lignes, et se termine par le même identifiant. Il est important que l’identifiant de fin soit placé exactement au début d’une nouvelle ligne, sans espaces ni indentation.

$cssCode = <<<CSS
body {
    background-color: #f4f4f4;
    font-family: Arial, sans-serif;
}
CSS;

Dans cet exemple, nous utilisons CSS comme identifiant, ce qui permet de structurer et d’injecter du code CSS de manière très claire. De la même manière, vous pouvez utiliser n’importe quel identifiant, tant qu’il est cohérent.

Que se passe-t-il si on utilise « TRUC » ou « BIDULE » comme identifiant ?

L’identifiant peut être n’importe quel mot, par exemple TRUC ou BIDULE, tant qu’il respecte les règles PHP (pas d’espaces, pas de chiffres en début de mot, etc.). Le mot choisi n’influence pas le fonctionnement du Heredoc, c’est seulement un marqueur pour délimiter le début et la fin de la chaîne.

$javascriptCode = <<<TRUC
function greet(name) {
    alert("Hello " + name + "!");
}
TRUC;

Le contenu entre <<<TRUC et TRUC; est traité comme une chaîne de caractères multi-lignes. Vous pouvez utiliser ce principe avec tout type de contenu (CSS, JavaScript, SQL, etc.). L’identifiant utilisé pour marquer le début et la fin du bloc Heredoc peut être personnalisé selon le type de contenu, par exemple HTML, CSS, ou JS, pour plus de clarté dans votre code. Cela permet de rendre le code plus lisible et de mieux organiser différents blocs, surtout dans des projets complexes.

L’identifiant doit être cohérent et ne doit pas entrer en conflit avec un mot réservé ou une variable existante. Bien qu’il puisse être n’importe quel mot valide, choisir un identifiant descriptif améliore la lisibilité et facilite la gestion du code, par opposition à un nom générique comme TRUC ou BIDULE.

Les Limites du Heredoc et comment les contourner

Bien que Heredoc soit puissant, il présente des limitations dans certains contextes. Toutefois, pour chaque situation problématique, il existe souvent une solution.

Heredoc dans une expression conditionnelle

Le code suivant ne fonctionne pas, car Heredoc ne peut pas être utilisé directement dans une expression conditionnelle :

if (true) {
    $texte = <<<TEXTE
    Ceci ne fonctionnera pas.
    TEXTE;
}

Solution : Pour contourner cette limitation, vous pouvez assigner la chaîne Heredoc à une variable avant d’entrer dans l’expression conditionnelle.

$texte = <<<TEXTE
Ceci fonctionne.
TEXTE;

if (true) {
    echo $texte;
}

Utilisation dans un tableau

PHP n’autorise pas l’utilisation de Heredoc directement dans des tableaux, de ce fait, le code suivant génère une erreur :

$tableau = [
    <<<TEXTE
    Chaîne 1
    TEXTE,
    <<<TEXTE
    Chaîne 2
    TEXTE,
];

Solution : Assignez d’abord les chaînes Heredoc à des variables avant de les inclure dans le tableau.

$texte1 = <<<TEXTE
Chaîne 1
TEXTE;

$texte2 = <<<TEXTE
Chaîne 2
TEXTE;

$tableau = [$texte1, $texte2];

Problèmes d’indentation du marqueur de fin

Comme précisé lors de l’introduction, si le marqueur de fin de Heredoc est mal positionné, ou simplement indenté, PHP ne reconnaîtra pas correctement la fin du bloc :

$texte = <<<TEXTE
Ceci fonctionnera,
mais la fin est mal indentée.
    TEXTE; // Cela génère une erreur.

Solution : Assurez-vous que le marqueur de fin est bien placé sans aucun espace ou indentation.

$texte = <<<TEXTE
    Ceci fonctionne correctement.
TEXTE;

L’usage de `<<-` dans d’autres langages et contournement en PHP

Dans certains langages comme Bash, il existe une variante de Heredoc, <<-, qui permet de gérer les indentations. Cela offre une flexibilité supplémentaire pour structurer le code de manière lisible, tout en permettant d’utiliser l’indentation dans le texte.

cat <<-EOF
    Ceci est du texte
    avec indentation dans Bash.
EOF

Grâce à <<-, le texte affiché conserve l’indentation souhaitée, tout en respectant une syntaxe plus claire dans le code source.

En PHP, il n’existe pas d’équivalent direct à <<-, mais on peut contourner ce manque en utilisant des fonctions comme ltrim pour nettoyer l’indentation après la génération de la chaîne.

$texte = <<<TEXT
    Ceci est un texte avec indentation.
    Grâce à ltrim, nous pouvons l'ajuster.
TEXT;

echo ltrim($texte);

Ce contournement permet de conserver une structure de code propre et lisible, tout en produisant du texte sans indentation indésirable, ce qui simplifie la lisibilité et la maintenance du code.

En utilisant cette approche, vous pouvez conserver une bonne organisation visuelle dans votre code PHP, surtout si vous travaillez avec du texte multi-lignes (HTML, JSON, etc.) qui sera traité ou affiché sans indentation.

Le Nowdoc : une alternative pour le texte brut

Nowdoc est une variante de Heredoc, introduite dans PHP 5.3, qui permet d’écrire du texte brut sans interpréter les variables. Cela est particulièrement utile lorsque vous voulez inclure du texte qui contient des variables ou du code PHP sans les évaluer.

$code = <<<'PHP'
echo "Le contenu de \$variable ne sera pas interprété.";
PHP;

Ici, \$variable est affiché littéralement sans être interprété par PHP.

Contexte d’emploi du Nowdoc

Inclusion de code source : Nowdoc est particulièrement utile pour stocker du code source dans une chaîne sans évaluation des variables. Cela est fréquent lorsqu’on doit afficher ou sauvegarder des blocs de code PHP, HTML ou JavaScript.

$phpTemplate = <<<'PHP'
<?php
echo "Hello, World!";
?>
PHP;

Ce modèle peut être utilisé tel quel sans évaluation, par exemple pour générer des fichiers ou afficher du code.

Templates dans des frameworks : Des frameworks comme Laravel et Symfony peuvent utiliser Nowdoc pour stocker des templates statiques. Par exemple, si vous devez insérer du contenu statique dans des fichiers de configuration ou des modèles d’e-mails, Nowdoc est une excellente solution.

$emailTemplate = <<<'EMAIL'
Cher utilisateur,

Merci de vous être inscrit sur notre plateforme.

Cordialement,
L'équipe.
EMAIL;

Heredoc dans d’autres langages

Heredoc existe dans de nombreux langages de programmation, où il est utilisé pour manipuler du texte multi-lignes ou des blocs de code, tout en permettant l’inclusion de variables.

Bash

Dans Bash, Heredoc est souvent utilisé pour envoyer du texte à des commandes ou pour générer des fichiers.

cat <<EOF
Ceci est un bloc de texte multi-lignes dans Bash.
EOF

Ce code envoie le texte à la commande cat, qui l’affiche ensuite dans la sortie standard.

Ruby

En Ruby, Heredoc est utilisé de manière similaire à PHP, notamment pour générer des chaînes multi-lignes.

texte = <<TEXT
Ceci est du texte multi-lignes en Ruby.
TEXT
puts texte

JavaScript (avec template literals)

Bien que JavaScript ne supporte pas Heredoc en tant que tel, il propose une alternative similaire avec les template literals, introduits dans ECMAScript 6 (ES6). Les backticks permettent d’insérer des chaînes multi-lignes tout en incluant des expressions dynamiques.

Exemple sans template literals (avant ES6) :

var name = "John";
var message = "Bonjour " + name + ",\nBienvenue sur notre site.";
console.log(message);

Cela nécessitait des concaténations de chaînes et des \n pour gérer les retours à la ligne.

Exemple avec template literals (ES6) :

let name = "John";
let message = `Bonjour ${name},
Bienvenue sur notre site.`;
console.log(message);

Les template literals simplifient considérablement l’écriture de chaînes multi-lignes et l’inclusion de variables. Le contenu devient plus lisible et plus naturel à écrire, en particulier lorsqu’il y a plusieurs lignes et des variables à intégrer.

Conclusion : Heredoc, Nowdoc et au-delà

Le Heredoc et le Nowdoc sont des outils puissants pour la gestion des chaînes de caractères multi-lignes dans PHP, mais leurs usages dépassent largement ce seul langage. Bien qu’ils soient principalement utilisés pour générer du contenu HTML ou du texte formaté avec des variables PHP, leurs équivalents dans d’autres langages, comme Bash, Ruby ou les template literals en JavaScript, montrent que cette approche a un impact large dans le monde du développement.

L’introduction de ces fonctionnalités a permis aux développeurs d’écrire du code plus lisible, plus clair et plus maintenable, en supprimant les tracas liés aux concaténations complexes et aux guillemets mal placés.