Heredoc i nowdoc w PHP: łańcuchy wielowierszowe

Heredoc to łańcuch wielowierszowy. Zacznij go od <<<EOT, napisz tekst w kolejnych liniach i zakończ EOT; w osobnej linii. Zmienne w środku są podstawiane jak w łańcuchu w podwójnych cudzysłowach.

<?php
$name = "Ada";
$items = 3;

$message = <<<EOT
Hello, $name.
You have $items items in your cart.
Quotes "like these" and 'these' need no escaping.
EOT;

echo $message;

Identyfikator (tutaj EOT) to litera lub podkreślnik, po których następują litery, cyfry lub podkreślniki. Zwykle wybiera się nazwy, które mówią, czym jest tekst: HTML, SQL, TEXT. Niektóre edytory, w tym PhpStorm, podświetlają treść jako ten język, gdy nazwa to HTML albo SQL.

Szablon HTML w heredoc

Heredoc to najczytelniejszy sposób zapisu bloku HTML z wartościami, bo znaczniki zachowują swój kształt i nic nie trzeba escapować. Wynik to HTML, więc edytor pokazuje go na karcie Page.

<?php
$product = [
    "name" => "Mechanical keyboard",
    "price" => 89.5,
    "tags" => ["usb-c", "hot-swap", "rgb"],
];

$tagList = "";
foreach ($product["tags"] as $tag) {
    $tagList .= "<li>$tag</li>";
}
$price = number_format($product["price"], 2);

echo <<<HTML
<style>
  .card { font-family: sans-serif; border: 1px solid #ccc; padding: 12px; width: 240px; }
  .price { color: #0a7; font-weight: bold; }
</style>
<div class="card">
  <h2>{$product['name']}</h2>
  <p class="price">\$$price</p>
  <ul>$tagList</ul>
</div>
HTML;

Dwa szczegóły w tym bloku: element tablicy jest objęty nawiasami klamrowymi, {$product['name']}, a dosłowny znak dolara przed ceną jest escapowany jako \$. Zmień nazwę albo dodaj znacznik i uruchom ponownie.

Wartości od użytkowników trzeba escapować, zanim trafią do HTML. Dlaczego i jak, wyjaśnia strona o htmlspecialchars.

Nowdoc: tekst bez interpolacji

Nowdoc ma identyfikator w pojedynczych cudzysłowach: <<<'EOT'. Nic w środku nie jest podstawiane, więc znaki dolara i ukośniki wsteczne zostają takie, jak je zapisano. Używaj go do przykładów kodu, wyrażeń regularnych i każdego tekstu, który zawiera $.

<?php
$name = "Ada";

$heredoc = <<<EOT
Hello, $name\tTab
EOT;

$nowdoc = <<<'EOT'
Hello, $name\tTab
EOT;

echo $heredoc . "\n";
echo $nowdoc . "\n";

Wcięcie znacznika zamykającego

Od PHP 7.3 znacznik zamykający może być wcięty, a to wcięcie jest usuwane z każdej linii treści. Dzięki temu heredoc w funkcji albo w if może podążać za wcięciem kodu, a spacje nie trafiają do łańcucha.

<?php
function welcome(string $name): string
{
    return <<<TEXT
        Hi $name,
          this line keeps 2 extra spaces.
        Bye.
        TEXT;
}

echo welcome("Grace");
echo "\n---\n";
echo json_encode(welcome("Grace"));

Linia z json_encode pokazuje wynik znak po znaku: z każdej linii usunięto 8 spacji, bo zamykające TEXT; jest wcięte o 8.

Linia treści wcięta mniej niż znacznik zamykający to błąd parsowania:

$html = <<<HTML
  <p>Hello</p>
    HTML;

PHP Parse error:  Invalid body indentation level (expecting an indentation level of at least 4) in /home/index.php on line 3

Tablice, obiekty i wywołania metod w heredoc

Heredoc działa według tych samych zasad co podwójne cudzysłowy. Proste zmienne działają same; dla kluczy tablic w cudzysłowach, zagnieżdżonych tablic, właściwości i wywołań metod użyj nawiasów klamrowych.

<?php
$order = ["id" => 1042, "items" => ["pen", "ink"]];
$date = new DateTimeImmutable("2026-03-14 09:30");

// A plain function cannot be called inside the string,
// but a variable holding a function name or closure can.
$upper = 'strtoupper';
$count = fn(array $a) => count($a);

echo <<<TEXT
Order #{$order['id']}
First item: {$order['items'][0]}
Placed: {$date->format('Y-m-d H:i')}
Items: {$count($order['items'])}
Shout: {$upper('done')}
TEXT;

Heredoc jako argument funkcji

Od PHP 7.3 po znaczniku zamykającym może w tej samej linii stać dalszy kod, więc heredoc można przekazać prosto do funkcji albo umieścić w tablicy. Z sprintf dostajesz szablon, którego symbole zastępcze wypełnisz później.

<?php
$template = <<<TEXT
Dear %s,
your invoice #%05d for %.2f EUR is due on %s.
TEXT;

echo sprintf($template, "Ada", 42, 129.9, "2026-04-01"), "\n\n";

$lines = [<<<A
    first entry
    A, "second entry"];
print_r($lines);

Częsty błąd: brak średnika albo dodatkowy tekst po znaczniku

Identyfikator zamykający musi być zapisany dokładnie tak jak przy otwarciu (ta sama wielkość liter), a to, co stoi po nim w tej linii, musi mieć sens jako PHP. EOT; kończy instrukcję, EOT, kontynuuje listę argumentów. Litera lub cyfra zaraz po znaczniku (EOTX;) go ukrywa, więc łańcuch biegnie do końca pliku, a PHP zgłasza syntax error, unexpected end of file. Odwrotna pułapka to linia treści, która zaczyna się od identyfikatora, po którym jest spacja lub znak interpunkcyjny, na przykład EOT is the marker: kończy łańcuch za wcześnie, a reszta tej linii jest czytana jako PHP (syntax error, unexpected identifier "is"). Wybierz identyfikator, który nigdy nie pojawia się na początku linii w tekście, na przykład HTML dla znaczników albo SQL dla zapytania.