<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.echo">
 <refnamediv>
  <refname>echo</refname>
  <refpurpose>Output one or more strings</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>echo</methodname>
   <methodparam rep="repeat"><type>string</type><parameter>expressions</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   Outputs one or more expressions, with no additional newlines or spaces.
  </simpara>
  <para>
   <literal>echo</literal> is not a function but a language construct.
   Its arguments are a list of expressions following the <literal>echo</literal>
   keyword, separated by commas, and not delimited by parentheses.
   Unlike some other language constructs, <literal>echo</literal> does not have
   any return value, so it cannot be used in the context of an expression.
  </para>
  <para>
   <literal>echo</literal> also has a shortcut syntax, where you can
   immediately follow the opening tag with an equals sign. This syntax is available
   even with the <link linkend="ini.short-open-tag">short_open_tag</link> configuration
   setting disabled.
   <informalexample>
    <programlisting role="php">
<![CDATA[
I have <?=$foo?> foo.
]]>
    </programlisting>
   </informalexample>
  </para>
  <para>
   The major differences to <function>print</function> are that
   <literal>echo</literal> accepts multiple arguments and doesn't have a return value.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>expressions</parameter></term>
     <listitem>
      <para>
       One or more string expressions to output, separated by commas.
       Non-string values will be coerced to strings, even when
       <link linkend="language.types.declarations.strict">the
       <literal>strict_types</literal> directive</link> is enabled.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><literal>echo</literal> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
echo "echo does not require parentheses.";

// Strings can either be passed individually as multiple arguments or
// concatenated together and passed as a single argument
echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', "\n";
echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n";

// No newline or space is added; the below outputs "helloworld" all on one line
echo "hello";
echo "world";

// Same as above
echo "hello", "world";

echo "This string spans
multiple lines. The newlines will be
output as well";

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

// The argument can be any expression which produces a string
$foo = "example";
echo "foo is $foo"; // foo is example

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

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

// However, the following examples will work:
($some_var) ? print 'true' : print 'false'; // print is also a construct, but
                                            // it is a valid expression, returning 1,
                                            // so it may be used in this context.

echo $some_var ? 'true': 'false'; // evaluating the expression first and passing it to echo
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><literal>echo</literal> is not an expression</title>
    <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
// Because echo does not behave as an expression, the following code is invalid.
($some_var) ? echo 'true' : echo 'false';
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.language-construct;

  <note>
   <title>Using with parentheses</title>
   <para>
    Surrounding a single argument to <literal>echo</literal> with parentheses will not
    raise a syntax error, and produces syntax which looks like a normal
    function call. However, this can be misleading, because the parentheses are actually
    part of the expression being output, not part of the <literal>echo</literal>
    syntax itself.

    <example>
     <title>Using Parentheses</title>
     <programlisting role="php">
     <![CDATA[
<?php
echo "hello", PHP_EOL;
// outputs "hello"

echo("hello"), PHP_EOL;
// also outputs "hello", because ("hello") is a valid expression

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

echo "hello", " world", PHP_EOL;
// outputs "hello world"

echo("hello"), (" world"), PHP_EOL;
// outputs "hello world"; the parentheses are part of each expression
?>
]]>
    </programlisting>
   </example>
  </para>

  <para>
    <example>
     <title>Invalid Expression</title>
     <programlisting role="php" annotations="non-interactive">
     <![CDATA[
<?php
echo("hello", " world"), PHP_EOL;
// Throws a Parse Error because ("hello", " world") is not a valid expression
?>
]]>
    </programlisting>
   </example>
  </para>
  </note>

  <tip>
   <para>
    Passing multiple arguments to <literal>echo</literal> can avoid
    complications arising from the precedence of the concatenation operator in
    PHP. For instance, the concatenation operator has higher precedence than
    the ternary operator, and prior to PHP 8.0.0 had the same precedence as addition
    and subtraction:
   </para>
   <programlisting role="php">
    <![CDATA[
<?php
// Below, the expression 'Hello ' . isset($name) is evaluated first,
// and is always true, so the argument to echo is always $name
echo 'Hello ' . isset($name) ? $name : 'John Doe' . '!';

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

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

// Again, adding parentheses ensures the intended order of evaluation
echo 'Sum: ' . (1 + 2);
]]>
   </programlisting>
   <para>
    If multiple arguments are passed in, then parentheses will not be
    required to enforce precedence, because each expression is separate:
   </para>
   <programlisting role="php">
<![CDATA[
<?php
echo "Hello ", isset($name) ? $name : "John Doe", "!";

echo "Sum: ", 1 + 2;
]]>
   </programlisting>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>print</function></member>
    <member><function>printf</function></member>
    <member><function>flush</function></member>
    <member><link linkend="language.types.string">Ways to specify literal strings</link></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->