Heredoc وNowdoc في PHP: النصوص متعددة الأسطر

Heredoc نص متعدد الأسطر. ابدأه بـ <<<EOT، واكتب النص في الأسطر التالية، ثم أنهِه بـ EOT; في سطر مستقل. تُستبدل المتغيرات داخله كما في النص بين علامتي تنصيص مزدوجتين.

<?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;

المعرّف (EOT هنا) حرف أو شرطة سفلية تليها أحرف أو أرقام أو شرطات سفلية. يختار المبرمجون أسماء تدل على محتوى النص: HTML وSQL وTEXT. وبعض المحررات، ومنها PhpStorm، تلوّن الجسم بصياغة تلك اللغة عندما يكون الاسم HTML أو SQL.

بناء قالب HTML باستخدام heredoc

Heredoc أوضح طريقة لكتابة كتلة HTML فيها قيم، لأن الوسوم تحتفظ بشكلها ولا شيء يحتاج إلى تهريب. المخرجات HTML، لذا يعرضها المحرر في تبويب 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;

تفصيلتان في هذا المثال: عنصر المصفوفة محاط بأقواس، {$product['name']}، وعلامة الدولار الحرفية قبل السعر مهرّبة هكذا \$. غيّر الاسم أو أضف وسمًا وشغّل الكود مرة أخرى.

يجب تهريب القيم القادمة من المستخدمين قبل وضعها في HTML. راجع htmlspecialchars لتعرف السبب والطريقة.

Nowdoc: نص بلا استيفاء

يضع nowdoc المعرّف بين علامتي تنصيص مفردتين: <<<'EOT'. لا يُستبدل شيء داخله، فتبقى علامات الدولار والشرطات المائلة العكسية كما كُتبت. استخدمه لأمثلة الكود والتعابير النمطية وأي نص يحتوي على $.

<?php
$name = "Ada";

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

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

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

إزاحة علامة الإغلاق

منذ PHP 7.3 يمكن إزاحة علامة الإغلاق، وتُزال تلك الإزاحة من كل سطر في الجسم. وهذا يسمح لـ heredoc داخل دالة أو if باتباع إزاحة الكود دون أن تدخل المسافات في النص.

<?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"));

يجعل سطر json_encode النتيجة مرئية محرفًا محرفًا: أُزيلت 8 مسافات من كل سطر، لأن TEXT; الختامية مزاحة بمقدار 8.

السطر الذي إزاحته أقل من علامة الإغلاق خطأ تحليل:

$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

المصفوفات والكائنات واستدعاءات الدوال التابعة داخل heredoc

يتبع heredoc قواعد علامتي التنصيص المزدوجتين نفسها. المتغيرات البسيطة تعمل وحدها، أما مفاتيح المصفوفات بين علامات تنصيص، والمصفوفات المتداخلة، والخصائص، واستدعاءات الدوال التابعة، فاستخدم لها الأقواس.

<?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 وسيطًا لدالة

منذ PHP 7.3 يمكن أن يلي علامةَ الإغلاق كودٌ آخر في السطر نفسه، لذا يمكن تمرير heredoc مباشرة إلى دالة أو وضعه في مصفوفة. ومع sprintf تحصل على قالب تُملأ عناصره النائبة لاحقًا.

<?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);

خطأ شائع: فاصلة منقوطة مفقودة أو نص زائد بعد العلامة

يجب أن يُكتب معرّف الإغلاق تمامًا كما فُتح (بحالة الأحرف نفسها)، وما يليه في ذلك السطر يجب أن يكون PHP صحيحة. تنهي EOT; تعليمة، وتكمل EOT, قائمة وسائط. الحرف أو الرقم بعد العلامة مباشرة (EOTX;) يخفيها، فيمتد النص إلى نهاية الملف وتبلغ PHP عن syntax error, unexpected end of file. والفخ المعاكس سطر في الجسم يبدأ بالمعرّف تليه مسافة أو علامة ترقيم، مثل EOT is the marker: ينهي النص مبكرًا، ويُقرأ باقي السطر على أنه PHP (syntax error, unexpected identifier "is"). اختر معرّفًا لا يظهر أبدًا في بداية سطر من النص، مثل HTML للوسوم أو SQL للاستعلام.