Strings mit HEREDOC-Syntax definieren (Thema: PHP Beispiele)

1. Hinweis

Der nachfolgende Artikel stimmt größtenteils mit dem über die NOWDOC-Syntax überein. Wenn man letzteren schon gelesen hat, reicht es, diesen hier grob zu überfliegen.

2. Einleitung

HEREDOC ist eine spezielle Syntax in PHP zum Markieren von längeren, häufig mehrzeiligen, Textabschnitten. Sie werden durch „<<<MARKIERUNG” eingeleitet, wobei „MARKIERUNG” ein beliebiger String sein kann. In der Regel wird er zur Verbesserung der Übersichtlichkeit groß geschrieben. Auf „<<<MARKIERUNG” muss ein Zeilenumbruch und anschließend der Text folgen. Dieser kann genauso wie zwischen doppelten Anführungszeichen geschrieben werden. Variablen werden auch hier automatisch von PHP erkannt und durch ihre Werte ersetzt. Im Unterschied zu doppelten Anführungszeichen können allerdings auch innerhalb des Strings wiederum doppelte Anführungszeichen platziert werden, ohne dass diese escapet werden müssen. Das Ende des HEREDOC-Abschnitts wird mit „MARKIERUNG;” gekennzeichnet, welches am Anfang einer neuen Zeile stehen muss.

Neben der HEREDOC-Syntax gibt es auch die NOWDOC-Syntax, welche in einem eigenen Artikel erläutert wird. Während bei HEREDOC in den Strings Variablen geparset werden, ist dies bei NOWDOC nicht der Fall. HEREDOC gleicht also der String-Definition über doppelte Anführungszeichen, NOWDOC eher der über einfache Anführungszeichen.

3. Beispiel: Ein einfacher String in HEREDOC-Syntax

In diesem Beispiel wird $heredoc über die HEREDOC-Syntax als String mit Inhalt „abcdefg” definiert.

<?php
	$heredoc = <<<STRING
abcdefg
STRING;
	var_dump($heredoc);
?>

string(7) "abcdefg" 

4. HEREDOC mit mehreren Zeilen

Ähnlich dem vorherigen Beispiel, diesmal geht der String aber über mehrere Zeilen.

<?php
	$heredoc = <<<STRING
abcdefg
abcdefg
abcdefg
STRING;
	var_dump($heredoc);
?>

string(25) "abcdefg
abcdefg
abcdefg"

5. HEREDOC und Einrückungen

In diesem Beispiel werden Einrückungen über Tabs vorgenommen. Wie bei der Ausgabe zu sehen ist, werden diese mit übernommen. Will man dies vermeiden, dann darf man in HEREDOC keine Zeilen einrücken.

<?php
	$heredoc = <<<STRING
		test
STRING;
	var_dump($heredoc);
?>

string(6) "		test"

6. HEREDOC mit anderen Start- und Endzeichen

Im nächsten Beispiel werden andere Bezeichnungen für die Start- und Endmarkierungen gewählt. Die Namensgebung erfolgt nach den selben Regeln wie bei Variablen: Klein- und Großbuchstaben, Zahlen und Unterstriche sind erlaubt. Der Name darf allerdings nicht mit einer Zahl beginnen.

<?php
	$heredoc1 = <<<X
123456789
X;
	var_dump($heredoc1);
	
	$heredoc2 = <<<__bla__
test123
__bla__;
	var_dump($heredoc2);
	
	$heredoc3 = <<<a1234
Noch ein String.
a1234;
	var_dump($heredoc3);
?>

string(9) "123456789"
string(7) "test123"
string(16) "Noch ein String."

7. HEREDOC mit Startmarkierung in Anführungszeichen

Optional kann die Startmarkierung auch in doppelte Anführungszeichen gesetzt werden. Dadurch wird die Syntax von HEREDOC ähnlicher zu NOWDOC, da bei letzterer einfache Anführungszeichen Pflicht sind.

<?php
	$heredoc = <<<"X"
asdasdasdasd
X;
	var_dump($heredoc);
?>

string(12) "asdasdasdasd"

8. Zugriff auf Variablen in HEREDOC

Innerhalb von HEREDOC werden Variablen automatisch durch ihre Werte ersetzt, so wie man es von der Stringdefinition bei doppelten Anführungszeichen her kennt.

<?php
	$x = 10000;
	$heredoc = <<<STRING
Der Wert von x ist: $x
STRING;
	var_dump($heredoc);
?>

string(25) "Der Wert von x ist: 10000"

9. Verwenden von Anführungszeichen innerhalb des Textes

Seine Stärke spielt HEREDOC bei mehrzeiligen Texten, welche auch Anführungszeichen enthalten können, aus. Der Text ist insgesamt einfacher zu lesen als bei normaler Definition über einfache oder doppelte Anführungszeichen.

<?php
	$heredoc = <<<STRING
Dies ist ein "Text", der auch 'Anführungszeichen' enthält,
was bei "normaler" Definition einige Schrägstriche/Backslashes zum
Escapen erfordern würde.
STRING;
	var_dump($heredoc);
?>

string(156) "Dies ist ein "Text", der auch 'Anführungszeichen' enthält,
was bei "normaler" Definition einige Schrägstriche/Backslashes zum
Escapen erfordern würde."

10. Die Start- und Endmarkierung darf im Text enthalten sein

Die Zeichen aus der Start- und Endmarkierung dürfen Teil des Textes sein. Auch eine Platzierung am Anfang einer Zeile ist erlaubt. In letzterem Fall muss allerdings auf die Zeichenkette mindestens ein weiteres Zeichen folgen, da es in HEREDOC prinzipiell nicht zwingend vorgeschrieben ist, den HEREDOC-Abschnitt mit einem Semikolon abzuschließen.

<?php
	$heredoc = <<<X
Dieser Text enthält ein X.
X;
	var_dump($heredoc);
?>

string(27) "Dieser Text enthält ein X."

In neuer Zeile, ohne weiteres Zeichen (erzeugt einen Fehler):

<?php
	$heredoc = <<<X
Dieser Text enthält ein X.
X
X;
	var_dump($heredoc);
?>

<br />
<b>Parse error</b>:  syntax error, unexpected T_STRING in <b>...\test.php</b> on line <b>5</b><br />

11. HEREDOC kann zu unschönem Code führen

Auf oberster bzw. globaler Ebene im Code ist die HEREDOC-Syntax zwar schön anzusehen, bei tieferer Verschachtelung aber kann sie zu unschönem Code führen, da der Text und die Endmarkierung am Anfang der Zeile stehen sollten bzw. müssen.

<?php
	class MyClass {
		function doSomething($a) {
			if ($a === true) {
				$str = <<<HEREDOC
Dies ist ein beliebiger Text.
Sogar mit mehreren Zeilen!
(Und noch eine dritte Zeile.)
HEREDOC;
				echo $str;
			}
		}
	}
	$obj = new MyClass();
	$obj->doSomething(true);
?>

Dies ist ein beliebiger Text.
Sogar mit mehreren Zeilen!
(Und noch eine dritte Zeile.)

12. HEREDOC bei Feldern von Klassen und bei Klassen-Konstanten

Genauso wie zur Definition von „normalen” Variablen kann HEREDOC auch verwendet werden, um Felder und Konstanten einer Klasse zu setzen.

<?php
class HeredocClass {
		public $v1 = <<<DOC
Test v1
DOC;
		public static $v2 = <<<DOC
Test v2
DOC;
		const v3 = <<<DOC
Test v3
DOC;
	}
	$obj = new HeredocClass();
	var_dump($obj->v1, $obj::$v2, $obj::v3);
?>

string(7) "Test v1"
string(7) "Test v2"
string(7) "Test v3"

13. HEREDOC als Parameter verwenden

Über HEREDOC definierte Strings müssen nicht zwangsweise Variablen zugewiesen werden. Stattdessen ist es auch möglich, sie direkt als Parameter zu verwenden. Nachfolgend wird dies dargestellt, indem an echo() ein über HEREDOC definierter String übergeben wird.

<?php
	echo <<<HEREDOC_MIT_ECHO
Heredoc lässt sich problemlos mit echo
verknüpfen, sodass der Heredoc-String direkt
ausgegeben wird.
HEREDOC_MIT_ECHO;
?>

Heredoc lässt sich problemlos mit echo
verknüpfen, sodass der Heredoc-String direkt
ausgegeben wird.

In diesem zweiten Beispiel wird ein HEREDOC-String an var_dump übergeben, vergleichbar mit dem vorherigen Beispiel.

<?php
	var_dump(<<<HEREDOC_MIT_VAR_DUMP
Heredoc mit var_dump
HEREDOC_MIT_VAR_DUMP
);
?>

string(21) "Heredoc mit var_dump"

14. Zeilenumbrüche vor dem Ende von HEREDOC

In diesem Beispiel wird analysiert, wie HEREDOC Zeilenumbrüche direkt vor der Endmarkierung behandelt. Dazu werden drei Zeilenumbrüche nach dem letzten Zeichen gesetzt. Wie zu sehen ist, wird der allerletzte Zeilenumbruch weggekürzt, die anderen beiden bleiben erhalten.

<?php
$str = <<<HEREDOC
X


HEREDOC;
	var_dump($str);
?>

string(5) "X

"

15. Leerzeichen vor dem Ende von HEREDOC

Analog zum vorherigen Beispiel wird nun untersucht, wie HEREDOC Leerzeichen vor seinem Ende behandelt. Diesmal werden drei Leerzeichen vor dem letzten Zeilenumbruch (welcher zwangsweise gesetzt werden muss) platziert. Wie der Ausgabe entnommen werden kann, kürzt HEREDOC die Leerzeichen nicht weg.

<?php
	$str = <<<HEREDOC
X   
HEREDOC;
	var_dump($str);
?>

string(4) "X   "

16. Die Markierung des Endes muss in einer neuen Zeile stehen

In diesem Beispiel wird testweise die Endmarkierung nicht an den Anfang einer neuen Zeile gesetzt. Das Ergebnis ist ein Parse Error. Die Endmarkierung muss also immer am Anfang einer Zeile stehen.

<?php
	$str = <<<HEREDOC
X HEREDOC;
	var_dump($str);
?>

<br />
<b>Parse error</b>:  syntax error, unexpected $end in <b>...\test.php</b> on line <b>5</b><br />

17. HEREDOC mit Fehlerunterdrückung

Soll innerhalb des HEREDOC-Abschnitts auf Array-Schlüssel zugegriffen werden, die potenziell nicht definiert sind, dann können Warnungen durch Verwendung des @-Zeichens unterdrückt werden. Dieses muss direkt vor der Startmarkierung platziert werden („@<<<MARKIERUNG”). Dabei ist zu bedenken, dass dies unschöner Stil ist, da die Warnungen noch immer erzeugt werden. Durch das @-Zeichen werden sie nur nicht mehr dargestellt.

<?php
	function printError($data) {
		echo @<<<ERR
Hallo {$data['username']},
es ist ein Fehler mit folgender Nachricht aufgetreten:
{$data['message']}
Ort des Fehlers: {$data['file']}, Zeile {$data['line']}.
ERR;
	}

	printError(array('message' => 'Ein Beispielproblem ist aufgetreten.', 'file'=>'index.php', 'line'=>127123));
?>

Hallo ,
es ist ein Fehler mit folgender Nachricht aufgetreten:
Ein Beispielproblem ist aufgetreten.
Ort des Fehlers: index.php, Zeile 127123.

Das selbe Beispiel ohne Fehlerunterdrückung (nur das @ fehlt):

<?php
	function printError($data) {
		echo <<<ERR
Hallo {$data['username']},
es ist ein Fehler mit folgender Nachricht aufgetreten:
{$data['message']}
Ort des Fehlers: {$data['file']}, Zeile {$data['line']}.
ERR;
	}

	printError(array('message' => 'Ein Beispielproblem ist aufgetreten.', 'file'=>'index.php', 'line'=>127123));
?>

<br />
<b>Notice</b>:  Undefined index: username in <b>...\test.php</b> on line <b>4</b><br />
Hallo ,
es ist ein Fehler mit folgender Nachricht aufgetreten:
Ein Beispielproblem ist aufgetreten.
Ort des Fehlers: index.php, Zeile 127123.