reference/strings/functions/echo.xml
7a3899eea90f3df8dcfe8fd350900162f3490bed
...
...
@@ -10,27 +10,23 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>void</type><methodname>echo</methodname>
13
-
<methodparam><type>string</type><parameter>arg1</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam>
13
+
<methodparam rep="repeat"><type>string</type><parameter>expressions</parameter></methodparam>
15
14
</methodsynopsis>
16
15
<simpara>
17
-
Outputs all parameters. No additional newline is appended.
16
+
Outputs one or more expressions, with no additional newlines or spaces.
18
17
</simpara>
19
18
<para>
20
-
<literal>echo</literal> is not actually a function (it is a
21
-
language construct), so you are not required to use parentheses
22
-
with it. <literal>echo</literal> (unlike some other language
23
-
constructs) does not behave like a function, so it cannot
24
-
always be used in the context of a function. Additionally, if you want to
25
-
pass more than one parameter to <literal>echo</literal>, the parameters
26
-
must not be enclosed within parentheses.
19
+
<literal>echo</literal> is not a function but a language construct.
20
+
Its arguments are a list of expressions following the <literal>echo</literal>
21
+
keyword, separated by commas, and not delimited by parentheses.
22
+
Unlike some other language constructs, <literal>echo</literal> does not have
23
+
any return value, so it cannot be used in the context of an expression.
27
24
</para>
28
25
<para>
29
26
<literal>echo</literal> also has a shortcut syntax, where you can
30
-
immediately follow the opening tag with an equals sign. Prior to PHP 5.4.0,
31
-
this short syntax only works with the
32
-
<link linkend="ini.short-open-tag">short_open_tag</link> configuration
33
-
setting enabled.
27
+
immediately follow the opening tag with an equals sign. This syntax is available
28
+
even with the <link linkend="ini.short-open-tag">short_open_tag</link> configuration
29
+
setting disabled.
34
30
<informalexample>
35
31
<programlisting role="php">
36
32
<![CDATA[
...
...
@@ -40,8 +36,8 @@ I have <?=$foo?> foo.
40
36
</informalexample>
41
37
</para>
42
38
<para>
43
-
The major differences to <literal>print</literal> are that
44
-
<literal>echo</literal> accepts an argument list and doesn't have a return value.
39
+
The major differences to <function>print</function> are that
40
+
<literal>echo</literal> accepts multiple arguments and doesn't have a return value.
45
41
</para>
46
42
</refsect1>
47
43

...
...
@@ -50,17 +46,13 @@ I have <?=$foo?> foo.
50
46
<para>
51
47
<variablelist>
52
48
<varlistentry>
53
-
<term><parameter>arg1</parameter></term>
54
-
<listitem>
55
-
<para>
56
-
The parameter to output.
57
-
</para>
58
-
</listitem>
59
-
</varlistentry>
60
-
<varlistentry>
61
-
<term><parameter>...</parameter></term>
49
+
<term><parameter>expressions</parameter></term>
62
50
<listitem>
63
51
<para>
52
+
One or more string expressions to output, separated by commas.
53
+
Non-string values will be coerced to strings, even when
54
+
<link linkend="language.types.declarations.strict">the
55
+
<literal>strict_types</literal> directive</link> is enabled.
64
56
</para>
65
57
</listitem>
66
58
</varlistentry>
...
...
@@ -83,22 +75,45 @@ I have <?=$foo?> foo.
83
75
<programlisting role="php">
84
76
<![CDATA[
85
77
<?php
86
-
echo "Hello World";
78
+
echo "echo does not require parentheses.";
87
79

88
80
// Strings can either be passed individually as multiple arguments or
89
81
// concatenated together and passed as a single argument
90
-
echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', chr(10);
82
+
echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', "\n";
91
83
echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n";
92
84

93
-
// Because echo does not behave like a function, the following code is invalid.
85
+
// No newline or space is added; the below outputs "helloworld" all on one line
86
+
echo "hello";
87
+
echo "world";
88
+

89
+
// Same as above
90
+
echo "hello", "world";
91
+

92
+
echo "This string spans
93
+
multiple lines. The newlines will be
94
+
output as well";
95
+

96
+
echo "This string spans\nmultiple lines. The newlines will be\noutput as well.";
97
+

98
+
// The argument can be any expression which produces a string
99
+
$foo = "example";
100
+
echo "foo is $foo"; // foo is example
101
+

102
+
$fruits = ["lemon", "orange", "banana"];
103
+
echo implode(" and ", $fruits); // lemon and orange and banana
104
+

105
+
// Non-string expressions are coerced to string, even if declare(strict_types=1) is used
106
+
echo 6 * 7; // 42
107
+

108
+
// Because echo does not behave as an expression, the following code is invalid.
94
109
($some_var) ? echo 'true' : echo 'false';
95
110

96
111
// However, the following examples will work:
97
112
($some_var) ? print 'true' : print 'false'; // print is also a construct, but
98
-
// it behaves like a function, so
99
-
// it may be used in this context.
113
+
// it is a valid expression, returning 1,
114
+
// so it may be used in this context.
100
115

101
-
echo $some_var ? 'true': 'false'; // changing the statement around
116
+
echo $some_var ? 'true': 'false'; // evaluating the expression first and passing it to echo
102
117
?>
103
118
]]>
104
119
</programlisting>
...
...
@@ -109,31 +124,82 @@ echo $some_var ? 'true': 'false'; // changing the statement around
109
124
<refsect1 role="notes">
110
125
&reftitle.notes;
111
126
&note.language-construct;
127
+

128
+
<note>
129
+
<title>Using with parentheses</title>
130
+
<para>
131
+
Surrounding a single argument to <literal>echo</literal> with parentheses will not
132
+
raise a syntax error, and produces syntax which looks like a normal
133
+
function call. However, this can be misleading, because the parentheses are actually
134
+
part of the expression being output, not part of the <literal>echo</literal>
135
+
syntax itself.
136
+
</para>
137
+
<para>
138
+
<example>
139
+
<title/>
140
+
<programlisting role="php">
141
+
<![CDATA[
142
+
<?php
143
+
echo "hello";
144
+
// outputs "hello"
145
+

146
+
echo("hello");
147
+
// also outputs "hello", because ("hello") is a valid expression
148
+

149
+
echo(1 + 2) * 3;
150
+
// outputs "9"; the parentheses cause 1+2 to be evaluated first, then 3*3
151
+
// the echo statement sees the whole expression as one argument
152
+

153
+
echo "hello", " world";
154
+
// outputs "hello world"
155
+

156
+
echo("hello"), (" world");
157
+
// outputs "hello world"; the parentheses are part of each expression
158
+

159
+
echo("hello", " world");
160
+
// Throws a Parse Error because ("hello", " world") is not a valid expression
161
+
?>
162
+
]]>
163
+
</programlisting>
164
+
</example>
165
+
</para>
166
+
</note>
167
+

112
168
<tip>
113
169
<para>
114
-
A benefit to passing in multiple arguments over using concatenation in
115
-
<function>echo</function> regards the precedence of the period operator in
116
-
PHP. If multiple arguments are passed in, then parentheses will not be
117
-
required to enforce precedence:
170
+
Passing multiple arguments to <literal>echo</literal> can avoid
171
+
complications arising from the precedence of the concatenation operator in
172
+
PHP. For instance, the concatenation operator has higher precedence than
173
+
the ternary operator, and prior to PHP 8.0.0 had the same precedence as addition
174
+
and subtraction:
118
175
</para>
119
176
<programlisting role="php">
120
-
<![CDATA[
177
+
<![CDATA[
121
178
<?php
122
-
echo "Sum: ", 1 + 2;
123
-
echo "Hello ", isset($name) ? $name : "John Doe", "!";
179
+
// Below, the expression 'Hello ' . isset($name) is evaluated first,
180
+
// and is always true, so the argument to echo is always $name
181
+
echo 'Hello ' . isset($name) ? $name : 'John Doe' . '!';
182
+

183
+
// The intended behaviour requires additional parentheses
184
+
echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';
185
+

186
+
// In PHP prior to 8.0.0, the below outputs "2", rather than "Sum: 3"
187
+
echo 'Sum: ' . 1 + 2;
188
+

189
+
// Again, adding parentheses ensures the intended order of evaluation
190
+
echo 'Sum: ' . (1 + 2);
124
191
]]>
125
192
</programlisting>
126
-

127
193
<para>
128
-
With concatenation, the period operator has the same precedence as
129
-
the addition operator, and higher precedence than the ternary operator, so parentheses must be used for the
130
-
correct behaviour:
194
+
If multiple arguments are passed in, then parentheses will not be
195
+
required to enforce precedence, because each expression is separate:
131
196
</para>
132
197
<programlisting role="php">
133
198
<![CDATA[
134
199
<?php
135
-
echo 'Sum: ' . (1 + 2);
136
-
echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';
200
+
echo "Hello ", isset($name) ? $name : "John Doe", "!";
201
+

202
+
echo "Sum: ", 1 + 2;
137
203
]]>
138
204
</programlisting>
139
205
</tip>
...
...
@@ -146,7 +212,7 @@ echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';
146
212
<member><function>print</function></member>
147
213
<member><function>printf</function></member>
148
214
<member><function>flush</function></member>
149
-
<member><link linkend="language.types.string.syntax.heredoc">Heredoc syntax</link></member>
215
+
<member><link linkend="language.types.string">Ways to specify literal strings</link></member>
150
216
</simplelist>
151
217
</para>
152
218
</refsect1>
153
219