<?xml version="1.0" encoding="utf-8"?>

<sect1 xml:id="language.types.string">

<title>Strings</title>

<para>

A <type>string</type> is a series of characters, where a character is

the same as a byte. This means that PHP only supports a 256-character set,

and hence does not offer native Unicode support. See

<link linkend="language.types.string.details">details of the string

type</link>.

</para>

<note>

<simpara>

On 32-bit builds, a <type>string</type> can be as large as up to 2GB

(2147483647 bytes maximum)

</simpara>

</note>

<sect2 xml:id="language.types.string.syntax">

<title>Syntax</title>

<para>

A <type>string</type> literal can be specified in four different ways:

</para>

<itemizedlist>

<listitem>

<simpara>

<link linkend="language.types.string.syntax.single">single quoted</link>

</simpara>

</listitem>

<listitem>

<simpara>

<link linkend="language.types.string.syntax.double">double quoted</link>

</simpara>

</listitem>

<listitem>

<simpara>

<link linkend="language.types.string.syntax.heredoc">heredoc syntax</link>

</simpara>

</listitem>

<listitem>

<simpara>

<link linkend="language.types.string.syntax.nowdoc">nowdoc syntax</link>

</simpara>

</listitem>

</itemizedlist>

<sect3 xml:id="language.types.string.syntax.single">

<title>Single quoted</title>

<para>

The simplest way to specify a <type>string</type> is to enclose it in single

quotes (the character <literal>'</literal>).

</para>

<para>

To specify a literal single quote, escape it with a backslash

(<literal>\</literal>). To specify a literal backslash, double it

(<literal>\\</literal>). All other instances of backslash will be treated

as a literal backslash: this means that the other escape sequences you

might be used to, such as <literal>\r</literal> or <literal>\n</literal>,

will be output literally as specified rather than having any special

meaning.

</para>

<note>

<simpara>

Unlike the <link linkend="language.types.string.syntax.double">double-quoted</link>

and <link linkend="language.types.string.syntax.heredoc">heredoc</link> syntaxes,

<link linkend="language.variables">variables</link> and escape sequences

for special characters will <emphasis>not</emphasis> be expanded when they

occur in single quoted <type>string</type>s.

</simpara>

</note>

<example>

<title>Syntax Variants</title>

<programlisting role="php">

</programlisting>

</example>

</sect3>

<sect3 xml:id="language.types.string.syntax.double">

<title>Double quoted</title>

<para>

If the <type>string</type> is enclosed in double-quotes (<literal>"</literal>), PHP will

interpret the following escape sequences for special characters:

</para>

<table>

<title>Escaped characters</title>

<tgroup cols="2">

<thead>

<row>

<entry>Sequence</entry>

<entry>Meaning</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>\n</literal></entry>

<entry>linefeed (LF or 0x0A (10) in ASCII)</entry>

</row>

<row>

<entry><literal>\r</literal></entry>

<entry>carriage return (CR or 0x0D (13) in ASCII)</entry>

</row>

<row>

<entry><literal>\t</literal></entry>

<entry>horizontal tab (HT or 0x09 (9) in ASCII)</entry>

</row>

<row>

<entry><literal>\v</literal></entry>

<entry>vertical tab (VT or 0x0B (11) in ASCII)</entry>

</row>

<row>

<entry><literal>\e</literal></entry>

<entry>escape (ESC or 0x1B (27) in ASCII)</entry>

</row>

<row>

<entry><literal>\f</literal></entry>

<entry>form feed (FF or 0x0C (12) in ASCII)</entry>

</row>

<row>

<entry><literal>\\</literal></entry>

<entry>backslash</entry>

</row>

<row>

<entry><literal>\$</literal></entry>

<entry>dollar sign</entry>

</row>

<row>

<entry><literal>\"</literal></entry>

<entry>double-quote</entry>

</row>

<row>

<entry><literal>\[0-7]{1,3}</literal></entry>

<entry>

Octal: the sequence of characters matching the regular expression <literal>[0-7]{1,3}</literal>

is a character in octal notation (e.g. <literal>"\101" === "A"</literal>),

which silently overflows to fit in a byte (e.g. <literal>"\400" === "\000"</literal>)

</entry>

</row>

<row>

<entry><literal>\x[0-9A-Fa-f]{1,2}</literal></entry>

<entry>

Hexadecimal: the sequence of characters matching the regular expression

<literal>[0-9A-Fa-f]{1,2}</literal> is a character in hexadecimal notation

(e.g. <literal>"\x41" === "A"</literal>)

</entry>

</row>

<row>

<entry><literal>\u{[0-9A-Fa-f]+}</literal></entry>

<entry>

Unicode: the sequence of characters matching the regular expression <literal>[0-9A-Fa-f]+</literal>

is a Unicode codepoint, which will be output to the string as that codepoint's UTF-8 representation.

The braces are required in the sequence. E.g. <literal>"\u{41}" === "A"</literal>

</entry>

</row>

</tbody>

</tgroup>

</table>

<para>

As in single quoted <type>string</type>s, escaping any other character will

result in the backslash being printed too.

</para>

<para>

The most important feature of double-quoted <type>string</type>s is the fact

that variable names will be expanded. See

<link linkend="language.types.string.parsing">string interpolation</link> for

details.

</para>

</sect3>

<sect3 xml:id="language.types.string.syntax.heredoc">

<title>Heredoc</title>

<simpara>

A third way to delimit <type>string</type>s is the heredoc syntax:

<literal>&lt;&lt;&lt;</literal>. After this operator, an identifier is

provided, then a newline. The <type>string</type> itself follows, and then

the same identifier again to close the quotation.

</simpara>

<simpara>

The closing identifier may be indented by space or tab, in which case

the indentation will be stripped from all lines in the doc string.

Prior to PHP 7.3.0, the closing identifier <emphasis>must</emphasis>

begin in the first column of the line.

</simpara>

<simpara>

Also, the closing identifier must follow the same naming rules as any

other label in PHP: it must contain only alphanumeric characters and

underscores, and must start with a non-digit character or underscore.

</simpara>

<example>

<title>Basic Heredoc example as of PHP 7.3.0</title>

<programlisting role="php">

</programlisting>

&example.outputs.73;

<screen>

</screen>

</example>

<simpara>

If the closing identifier is indented further than any lines of the body, then a <classname>ParseError</classname> will be thrown:

</simpara>

<example>

<title>Closing identifier must not be indented further than any lines of the body</title>

<programlisting role="php">

</programlisting>

&example.outputs.73;

<screen>

</screen>

</example>

<simpara>

If the closing identifier is indented, tabs can be used as well, however,

tabs and spaces <emphasis>must not</emphasis> be intermixed regarding

the indentation of the closing identifier and the indentation of the body

(up to the closing identifier). In any of these cases, a <classname>ParseError</classname> will be thrown.

These whitespace constraints have been included because mixing tabs and

spaces for indentation is harmful to legibility.

</simpara>

<example>

<title>Different indentation for body (spaces) closing identifier</title>

<programlisting role="php" annotations="non-interactive">

</programlisting>

&example.outputs.73;

<screen>

</screen>

</example>

<simpara>

The closing identifier for the body string is not required to be

followed by a semicolon or newline. For example, the following code

is allowed as of PHP 7.3.0:

</simpara>

<example>

<title>Continuing an expression after a closing identifier</title>

<programlisting role="php">

</programlisting>

&example.outputs.73;

<screen>

</screen>

</example>

<warning>

<simpara>

If the closing identifier was found at the start of a line, then

regardless of whether it was a part of another word, it may be considered

as the closing identifier and causes a <classname>ParseError</classname>.

</simpara>

<example>

<title>Closing identifier in body of the string tends to cause ParseError</title>

<programlisting role="php">

</programlisting>

&example.outputs.73;

<screen>

</screen>

</example>

<simpara>

To avoid this problem, it is safe to follow the simple rule:

<emphasis>do not choose a word that appears in the body of the text

as a closing identifier</emphasis>.

</simpara>

</warning>

<warning>

<simpara>

Prior to PHP 7.3.0, it is very important to note that the line with the

closing identifier must contain no other characters, except a semicolon

(<literal>;</literal>).

That means especially that the identifier

<emphasis>may not be indented</emphasis>, and there may not be any spaces

or tabs before or after the semicolon. It's also important to realize that

the first character before the closing identifier must be a newline as

defined by the local operating system. This is <literal>\n</literal> on

UNIX systems, including macOS. The closing delimiter must also be

followed by a newline.

</simpara>

<simpara>

If this rule is broken and the closing identifier is not "clean", it will

not be considered a closing identifier, and PHP will continue looking for

one. If a proper closing identifier is not found before the end of the

current file, a parse error will result at the last line.

</simpara>

<example>

<title>Invalid example, prior to PHP 7.3.0</title>

<programlisting role="php">

<!-- This is an INVALID example -->

</programlisting>

</example>

<example>

<title>Valid example, even prior to PHP 7.3.0</title>

<programlisting role="php">

<!-- This is a VALID example -->

</programlisting>

</example>

<para>

Heredocs containing variables can not be used for initializing class properties.

</para>

</warning>

<para>

Heredoc text behaves just like a double-quoted <type>string</type>, without

the double quotes. This means that quotes in a heredoc do not need to be

escaped, but the escape codes listed above can still be used. Variables are

expanded, but the same care must be taken when expressing complex variables

inside a heredoc as with <type>string</type>s.

</para>

<example>

<title>Heredoc string quoting example</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<para>

It is also possible to use the Heredoc syntax to pass data to function

arguments:

</para>

<example>

<title>Heredoc in arguments example</title>

<programlisting role="php">

</programlisting>

</example>

<para>

It's possible to initialize static variables and class

properties/constants using the Heredoc syntax:

</para>

<example>

<title>Using Heredoc to initialize static values</title>

<programlisting role="php" annotations="non-interactive">

</programlisting>

</example>

<para>

The opening Heredoc identifier may optionally be

enclosed in double quotes:

</para>

<example>

<title>Using double quotes in Heredoc</title>

<programlisting role="php">

</programlisting>

</example>

</sect3>

<sect3 xml:id="language.types.string.syntax.nowdoc">

<title>Nowdoc</title>

<para>

Nowdocs are to single-quoted strings what heredocs are to double-quoted

strings. A nowdoc is specified similarly to a heredoc, but <emphasis>no

String interpolation is done</emphasis> inside a nowdoc. The construct is ideal for

embedding PHP code or other large blocks of text without the need for

escaping. It shares some features in common with the SGML

<literal>&lt;![CDATA[ ]]&gt;</literal> construct, in that it declares a

block of text which is not for parsing.

</para>

<para>

A nowdoc is identified with the same <literal>&lt;&lt;&lt;</literal>

sequence used for heredocs, but the identifier which follows is enclosed in

single quotes, e.g. <literal>&lt;&lt;&lt;'EOT'</literal>. All the rules for

heredoc identifiers also apply to nowdoc identifiers, especially those

regarding the appearance of the closing identifier.

</para>

<example>

<title>Nowdoc string quoting example</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<example>

<title>Nowdoc string quoting example with variables</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<example>

<title>Static data example</title>

<programlisting role="php" annotations="non-interactive">

</programlisting>

</example>

</sect3>

<sect3 xml:id="language.types.string.parsing">

<title>String interpolation</title>

<simpara>

When a <type>string</type> is specified in double quotes or with heredoc,

<link linkend="language.variables">variables</link> can be substituted within it.

</simpara>

<simpara>

There are two types of syntax: a

<link linkend="language.types.string.parsing.basic">basic</link> one and an

<link linkend="language.types.string.parsing.advanced">advanced</link> one.

The basic syntax is the most common and convenient. It provides a way to

embed a variable, an <type>array</type> value, or an <type>object</type>

property in a <type>string</type> with a minimum of effort.

</simpara>

<sect4 xml:id="language.types.string.parsing.basic">

<title>Basic syntax</title>

<simpara>

If a dollar sign (<literal>$</literal>) is encountered, the characters

that follow it which can be used in a variable name will be interpreted

as such and substituted.

</simpara>

<example>

<title>String Interpolation</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<simpara>

Formally, the structure for the basic variable substitution syntax is

as follows:

</simpara>

<informalexample>

<programlisting>

</programlisting>

</informalexample>

<warning>

<para>

The <literal>${ expression }</literal> syntax is deprecated as of

PHP 8.2.0, as it can be interpreted as

<link linkend="language.variables.variable">variable variables</link>:

<informalexample>

<programlisting role="php">

</programlisting>

&example.outputs.82;

<screen>

</screen>

&example.outputs;

<screen>

</screen>

</informalexample>

The <link linkend="language.types.string.parsing.advanced">advanced</link>

string interpolation syntax should be used instead.

</para>

</warning>

<note>

<simpara>

If it is not possible to form a valid name the dollar sign remains

as verbatim in the string:

</simpara>

<informalexample>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</informalexample>

</note>

<example>

<title>Interpolating the value of the first dimension of an array or property</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<note>

<simpara>

The array key must be unquoted, and it is therefore not possible to

refer to a constant as a key with the basic syntax. Use the

<link linkend="language.types.string.parsing.advanced">advanced</link>

syntax instead.

</simpara>

</note>

<simpara>

As of PHP 7.1.0 also <emphasis>negative</emphasis> numeric indices are

supported.

</simpara>

<example><title>Negative numeric indices</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<simpara>

For anything more complex, the

<link linkend="language.types.string.parsing.advanced">advanced</link>

syntax must be used.

</simpara>

</sect4>

<sect4 xml:id="language.types.string.parsing.advanced">

<title>Advanced (curly) syntax</title>

<simpara>

The advanced syntax permits the interpolation of

<emphasis>variables</emphasis> with arbitrary accessors.

</simpara>

<simpara>

Any scalar variable, array element or object property

(<modifier>static</modifier> or not) with a

<type>string</type> representation can be included via this syntax.

The expression is written the same way as it would appear outside the

<type>string</type>, and then wrapped in <literal>{</literal> and

<literal>}</literal>. Since <literal>{</literal> can not be escaped, this

syntax will only be recognised when the <literal>$</literal> immediately

follows the <literal>{</literal>. Use <literal>{\$</literal> to get a

literal <literal>{$</literal>. Some examples to make it clear:

</simpara>

<example>

<title>Curly Syntax</title>

<programlisting role="php">

</programlisting>

</example>

<note>

<simpara>

As this syntax allows arbitrary expressions it is possible to use

<link linkend="language.variables.variable">variable variables</link>

within the advanced syntax.

</simpara>

</note>

</sect4>

</sect3>

<sect3 xml:id="language.types.string.substr">

<title>String access and modification by character</title>