A here document (also called a here-document, a heredoc, a hereis, a here-string or a here-script) is a way of specifying a string literal in command line shells including Unix shells and in programming or scripting languages such as Perl, PHP, Python, PowerShell and Ruby. It preserves the line breaks and other whitespace (including indentation) in the text. Some languages allow variable substitution and command substitution inside the string.
The most common syntax for here documents is << followed by a delimiting identifier, followed, starting on the next line, by the text to be quoted, and then closed by the same identifier on its own line.
In order to allow people to easily write large amounts of text from within PHP, but without the need to constantly escape things, heredoc syntax was developed. Heredoc might be a little tricky to understand at first, but it’s actually a big help. Put simply, it allows you to define your own string limiter so that you can make it something other than a double or single quote. So, for example, we could use the string “EOT” (end of text) for our delimiter, meaning that we can use double quotes and single quotes freely within the body of the text – the string only ends when we type EOT.
It is a little more complicated than that in practice, but not much – the string delimiter needs to be by itself on a line, in the very first column. That is, you cannot add spacing or tabs around it.
Take a look at this example:
<?php $mystring = <<<EOT This is some PHP text. It is completely free I can use “double quotes” and ‘single quotes’, plus $variables too, which will be properly converted to their values, you can even type EOT, as long as it is not alone on a line, like this: EOT; ?>There are several key things to note about heredoc, and the example above:
-
You can use anything you like; “EOT” is just an example
-
You need to use <<< before the delimiter to tell PHP you want to enter heredoc mode
-
Variable substitution is used in PHP, which means you do need to escape dollar symbols – if you do not, PHP will attempt variable replacement.
-
You can use your delimiter anywhere in the text, but not in the first column of a new line
-
At the end of the string, just type the delimiter with no spaces around it, followed by a semi-colon to end the statement
Without heredoc syntax, complicated string assignments can quickly become very messy. Heredoc is not used all that often in the wild – very often you will wish it were used more, because too many scripts you will come across have messy code as a result of not using heredoc!
