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

1. Hinweis

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

2. Einleitung

NOWDOC 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. Im Gegensatz zu HEREDOC muss er zwangsweise in einfache Anführungszeichen gesetzt werden. Auf „<<<'MARKIERUNG'” muss ein Zeilenumbruch und anschließend der Text folgen. Dieser kann genauso wie zwischen einfachen Anführungszeichen geschrieben werden. Entsprechend werden Variablen nicht ersetzt. (Sollen diese ersetzt werden, dann sollte man die HEREDOC-Syntax verwenden.) Im Unterschied zur Schreibweise über einfache Anführungszeichen können allerdings auch innerhalb des Strings wiederum einfache Anführungszeichen platziert werden, ohne dass diese escapet werden müssen. Das Ende des NOWDOC-Abschnitts wird mit „MARKIERUNG;” gekennzeichnet, welches am Anfang einer neuen Zeile stehen muss.

3. Beispiel: Ein einfacher String in NOWDOC-Syntax

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

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

string(7) "abcdefg"

4. Beispiel: NOWDOC mit mehreren Zeilen

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

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

string(25) "abcdefg
abcdefg
abcdefg"

5. NOWDOC 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 NOWDOC keine Zeilen einrücken.

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

string(6) "		test"

6. NOWDOC 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
	$nowdoc1 = <<<'X'
123456789
X;
	var_dump($nowdoc1);
	
	$nowdoc2 = <<<'__bla__'
test123
__bla__;
	var_dump($nowdoc2);
	
	$nowdoc3 = <<<'a1234'
Noch ein String.
a1234;
	var_dump($nowdoc3);
?>

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

7. Startmarkierung muss in einfache Anführungszeichen gesetzt werden

Während es bei HEREDOC optional ist, die Startmarkierung in doppelte Anführungszeichen zu setzen, ist es bei NOWDOC Pflicht, diese mit einfachen Anführungszeichen zu umgeben. Lässt man sie weg, erhält man wieder HEREDOC-Syntax, in welcher Variablen automatisch ersetzt werden:

<?php
	$x = 123;
	$notNowdoc = <<<'X'
Dies ist ein Beispiel. Das ist x: $x. Ende.
X;
	var_dump($notNowdoc);
?>

string(44) "Dies ist ein Beispiel. Das ist x: 123. Ende."

8. Zugriff auf Variablen ist in NOWDOC nicht möglich

NOWDOC verhält sich vergleichbar zur Definition von Strings über einfache Anführungszeichen. Daher werden in NOWDOC-Abschnitten keine Variablen ersetzt.

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

string(22) "Der Wert von x ist: $x"

9. Verwenden von Anführungszeichen innerhalb des Textes

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

<?php
	$nowdoc = <<<'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($nowdoc);
?>

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 NOWDOC prinzipiell nicht zwingend vorgeschrieben ist, den NOWDOC-Abschnitt mit einem Semikolon abzuschließen.

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

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

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

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

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

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

Auf oberster bzw. globaler Ebene im Code ist die NOWDOC-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 = <<<'NOWDOC'
Dies ist ein beliebiger Text.
Sogar mit mehreren Zeilen!
(Und noch eine dritte Zeile.)
NOWDOC;
				echo $str;
			}
		}
	}
	$obj = new MyClass();
	$obj->doSomething(true);
?>

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

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

Genauso wie für „normale” Variablen kann NOWDOC auch verwendet werden, um Felder und Konstanten einer Klasse zu definieren.

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

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

13. NOWDOC und echo verbinden

Über NOWDOC 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 NOWDOC definierter String übergeben wird.

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

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

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

<?php
	var_dump(<<<'NOWDOC_MIT_VAR_DUMP'
Nowdoc mit var_dump
NOWDOC_MIT_VAR_DUMP
);
?>

string(19) "Nowdoc mit var_dump"

14. Zeilenumbrüche vor dem Ende von NOWDOC

In diesem Beispiel wird analysiert, wie NOWDOC 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 = <<<'NOWDOC'
X


NOWDOC;
	var_dump($str);
?>

string(5) "X

"

15. Leerzeichen vor dem Ende von NOWDOC

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

<?php
	$str = <<<'NOWDOC'
X   
NOWDOC;
	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 = <<<'NOWDOC'
X NOWDOC;
	var_dump($str);
?>

<br />
<b>Parse error</b>:  syntax error, unexpected $end, expecting T_VARIABLE or T_END_HEREDOC or T_DOLLAR_OPEN_CURLY_BRACES or T_CURLY_OPEN in <b>...\test.php</b> on line <b>5</b><br />

17. Code-Abschnitte mit NOWDOC-Syntax auskommentieren

Die NOWDOC-Syntax kann zweckentfremdet werden, um größere Abschnitte von Code „auszukommentieren”. Auch wenn diese wiederum Kommentarblöcke oder andere NOWDOC-Abschnitte enthalten, gibt es dabei keine Probleme. Mit HEREDOC ist dies nicht möglich, da im auskommentierten Abschnitt enthaltene Variablen ersetzt werden würden.

<?php
	echo("Etwas Code hier.");

	<<<'AUSKOMMENTIERT'

	/**
	 * Eine einfache Funktion, die nichts macht.
	 **/
	function bla() {
		$var = 1;
		if (true) {
			return;
		}
		// else do nothing.
	}

	$var = 'bla';
	echo($var);

AUSKOMMENTIERT;

	echo("Ende");
?>

Etwas Code hier.Ende