Escrever strings multi-linhas em PHP

Para escrever uma string multilinha em PHP, use heredoc ou nowdoc para texto literal distribuído por várias linhas, insira \n ou \r\n numa string entre aspas duplas, ou acrescente fragmentos com .= e PHP_EOL. Estas abordagens colocam caracteres de quebra de linha na string; não controlam a quebra visual do texto, que depende de onde este é apresentado. Escolha a forma que deixa clara a interpolação e a convenção de quebra de linha necessária.

Usar heredoc ou nowdoc em literais de string multilinha

Heredoc e nowdoc permitem escrever uma string ao longo de várias linhas do código-fonte, sem inserir uma sequência de escape em cada quebra. Heredoc funciona como uma string entre aspas duplas, pelo que PHP interpola variáveis. Nowdoc funciona como uma string entre aspas simples, pelo que os nomes das variáveis permanecem literais. O identificador de fecho tem de corresponder ao identificador de abertura; ele próprio é o delimitador de fecho e tem de respeitar as regras de identificadores de PHP. No exemplo, TEXT é usado tanto na abertura como no delimitador de fecho.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

<?php
$name = 'Mina';
$message = <<<TEXT
Hello, $name.
Your report is ready.
TEXT;

$template = <<<'TEXT'
Hello, $name.
Your report is ready.
TEXT;

echo $message, PHP_EOL, $template;

O valor de heredoc contém Mina no lugar de $name. No valor de nowdoc, $name permanece no texto. Ambos os valores contêm uma quebra de linha entre as duas linhas do código-fonte. Use heredoc para modelos legíveis com valores de variáveis e nowdoc quando o conteúdo deva permanecer literal. O exemplo apresenta «Hello, Mina.» e «Your report is ready.» em heredoc, e «Hello, $name.» e «Your report is ready.» em nowdoc. Estes rótulos permanecem em inglês no exemplo imutável.

Inserir quebras de linha com sequências de escape

Numa string entre aspas duplas, \n acrescenta um carácter de avanço de linha. Use-o quando quiser manter uma string curta numa única linha do código-fonte ou controlar exatamente onde o texto passa à linha seguinte. Duas sequências \n consecutivas deixam uma linha em branco entre os textos. Uma string entre aspas simples não interpreta \n como avanço de linha; por isso, use aspas duplas nesta forma.

A sequência \r\n contém um retorno de carro seguido de um avanço de linha. Em conjunto, estes caracteres são normalmente tratados como uma única quebra de linha pelos visualizadores de texto. O retorno de carro não faz com que PHP mova um ponteiro de texto para a esquerda; é um carácter da string. Escolha esta sequência quando o formato de destino exigir especificamente CRLF, como num ficheiro de texto ao estilo do Windows. Para separar linhas segundo a convenção da plataforma atual, use PHP_EOL, como explicado abaixo.

Construir strings multilinha com concatenação e PHP_EOL

O operador .= acrescenta o valor do lado direito à string do lado esquerdo. Comece pelo primeiro fragmento e, em seguida, acrescente cada fragmento seguinte juntamente com um separador. PHP_EOL fornece a sequência de quebra de linha convencionalmente usada pela plataforma onde PHP está a ser executado.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

<?php
$message = 'First line';
$message .= PHP_EOL . 'Second line';
$message .= PHP_EOL . 'Third line';
echo $message;

Esta forma sequencial facilita a leitura de cada adição: após a primeira atribuição, $message contém o texto acumulado, e cada .= acrescenta conteúdo. Insira PHP_EOL antes de um fragmento quando este tiver de começar numa nova linha. O fragmento final não precisa de um separador no fim, a menos que o sistema que o recebe o exija. O exemplo apresenta «First line», «Second line» e «Third line» em linhas sucessivas; estes rótulos permanecem em inglês no exemplo imutável.

Escolher um formato de quebra de linha adequado ao caso de uso

Use PHP_EOL quando a string for escrita como texto normal para a plataforma atual e a quebra de linha convencional dessa plataforma for adequada. É uma constante da plataforma, não uma garantia de que todos os sistemas destinatários aceitem os mesmos bytes. Se um protocolo, formato de ficheiro ou serviço externo especificar LF ou CRLF, inclua essa sequência explícita em vez de depender da plataforma anfitriã.

Heredoc e nowdoc são sobretudo formas de expressar conteúdo literal multilinha e de escolher se as variáveis são interpoladas; as quebras de linha literais no código-fonte passam a fazer parte da string. As sequências de escape são úteis para strings curtas ou quando é necessário um separador preciso. A concatenação é útil quando se juntam partes provenientes de variáveis ou de valores calculados. Em todos os casos, verifique os requisitos do destino: um terminal, navegador, ficheiro de texto ou protocolo pode apresentar ou interpretar as quebras de linha de formas diferentes.