basic-syntax.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="language.basic-syntax" xmlns="http://docbook.org/ns/docbook">
  <title>Basic syntax</title>
  <sect1 xml:id="language.basic-syntax.phptags">
   <title>PHP tags</title>
   <para>
    When PHP parses a file, it looks for opening and closing tags, which are
    <literal>&lt;?php</literal> and <literal>?&gt;</literal> which tell PHP to
    start and stop interpreting the code between them. Parsing in this manner
    allows PHP to be embedded in all sorts of different documents, as
    everything outside of a pair of opening and closing tags is ignored by the
    PHP parser.
   </para>
   <para>
    PHP also allows for short open tag <literal>&lt;?</literal> (which is
    discouraged since it is only available if enabled using the
    <link linkend="ini.short-open-tag">short_open_tag</link> &php.ini;
    configuration file directive, or if PHP was configured with the
    <option>--enable-short-tags</option> option).
   </para>
   <para>
    If a file is pure PHP code, it is preferable to omit the PHP closing tag
    at the end of the file.  This prevents accidental whitespace or new lines
    being added after the PHP closing tag, which may cause unwanted effects
    because PHP will start output buffering when there is no intention from
    the programmer to send any output at that point in the script.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
echo "Hello world";

// ... more code

echo "Last statement";

// the script ends here with no PHP closing tag
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    <table>
     &reftitle.changelog;
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Version;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>7.0.0</entry>
         <entry>
          The ASP tags <code>&lt;%</code>, <code>%&gt;</code>,
          <code>&lt;%=</code>, and the script tag
          <code>&lt;script language="php"&gt;</code> are removed from PHP.
         </entry>
       </row>
       <row>
        <entry>5.4.0</entry>
         <entry>
          The tag &lt;?= is always available regardless of the short_open_tag ini setting.
         </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </sect1>
  <sect1 xml:id="language.basic-syntax.phpmode">
   <title>Escaping from HTML</title>
   <para>
    Everything outside of a pair of opening and closing tags is ignored by the
    PHP parser which allows PHP files to have mixed content.  This allows PHP
    to be embedded in HTML documents, for example to create templates.
    <example>
     <programlisting role="php">
<![CDATA[
<p>This is going to be ignored by PHP and displayed by the browser.</p>
<?php echo 'While this is going to be parsed.'; ?>
<p>This will also be ignored by PHP and displayed by the browser.</p>
]]>
     </programlisting>
    </example>
    This works as expected, because when the PHP interpreter hits the ?&gt; closing
    tags, it simply starts outputting whatever it finds (except for an
    immediately following newline - see
    <link linkend="language.basic-syntax.instruction-separation">instruction separation</link>)
    until it hits another opening tag unless in the middle of a conditional
    statement in which case the interpreter will determine the outcome of the
    conditional before making a decision of what to skip over.
    See the next example.
   </para>
   <para>
    Using structures with conditions
    <example>
     <title>Advanced escaping using conditions</title>
     <programlisting role="php">
<![CDATA[
<?php if ($expression == true): ?>
  This will show if the expression is true.
<?php else: ?>
  Otherwise this will show.
<?php endif; ?>
]]>
     </programlisting>
    </example>
    In this example PHP will skip the blocks where the condition is not met, even
    though they are outside of the PHP open/close tags, PHP skips them according
    to the condition since the PHP interpreter will jump over blocks contained
    within a condition what is not met.
   </para>
   <para>
    For outputting large blocks of text, dropping out of PHP parsing mode is
    generally more efficient than sending all of the text through
    <function>echo</function> or <function>print</function>.
   </para>
   <para>
    In PHP 5, there are up to five different pairs of opening and closing tags
    available in PHP, depending on how PHP is configured. Two of these,
    <code>&lt;?php ?&gt;</code> and
    <code>&lt;script language="php"&gt; &lt;/script&gt;</code>, are always
    available. There is also the short echo tag <code>&lt;?= ?&gt;</code>,
    which is always available in PHP 5.4.0 and later.
   </para>
   <para>
    The other two are short tags and <productname>ASP</productname> style
    tags. As such, while some people find short tags and
    <productname>ASP</productname> style tags convenient, they are less
    portable, and generally not recommended.
    <note>
     <para>
      Also note that if you are embedding PHP within XML or XHTML
      you will need to use the &lt;?php ?&gt; tags to remain
      compliant with standards.
     </para>
    </note>
   </para>
   <para>
    PHP 7 removes support for <productname>ASP</productname> tags and
    <code>&lt;script language="php"&gt;</code> tags. As such, we recommend
    only using <code>&lt;?php ?&gt;</code> and <code>&lt;?= ?&gt;</code> when
    writing PHP code to maximise compatibility.
   </para>
   <para>
    <example>
     <title>PHP Opening and Closing Tags</title>
     <programlisting role="php">
<![CDATA[
1.  <?php echo 'if you want to serve PHP code in XHTML or XML documents,
                use these tags'; ?>

2.  You can use the short echo tag to <?= 'print this string' ?>.
    It's always enabled in PHP 5.4.0 and later, and is equivalent to
    <?php echo 'print this string' ?>.

3.  <? echo 'this code is within short tags, but will only work '.
            'if short_open_tag is enabled'; ?>

4.  <script language="php">
        echo 'some editors (like FrontPage) don\'t
              like processing instructions within these tags';
    </script>
    This syntax is removed in PHP 7.0.0.

5.  <% echo 'You may optionally use ASP-style tags'; %>
    Code within these tags <%= $variable; %> is a shortcut for this code <% echo $variable; %>
    Both of these syntaxes are removed in PHP 7.0.0.
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Short tags (example three) are only available when they are
    enabled via the <link linkend="ini.short-open-tag">short_open_tag</link>
    &php.ini; configuration file directive, or if PHP was configured
    with the <option>--enable-short-tags</option> option.
   </para>
   <para>
    <productname>ASP</productname> style tags (example five) are only
    available when they are enabled via the
    <link linkend="ini.asp-tags">asp_tags</link> &php.ini; configuration file
    directive, and have been removed in PHP 7.0.0.
   </para>
   <para>
    <note>
     <para>
      Using short tags should be avoided when developing applications
      or libraries that are meant for redistribution, or deployment on
      PHP servers which are not under your control, because short tags
      may not be supported on the target server.  For portable,
      redistributable code, be sure not to use short tags.
     </para>
    </note>
    <note>
     <para>
      In PHP 5.2 and earlier, the parser does not allow the
      <literal>&lt;?php</literal> opening tag to be the only thing in a file.
      This is allowed as of PHP 5.3 provided there are one or more whitespace
      characters after the opening tag.
     </para>
    </note>
    <note>
     <para>
      Starting with PHP 5.4, short echo tag <literal>&lt;?=</literal> is always recognized and
      valid, regardless of the <link linkend="ini.short-open-tag">short_open_tag</link> setting.
     </para>
    </note>
   </para>
  </sect1>
  <sect1 xml:id="language.basic-syntax.instruction-separation">
   <title>Instruction separation</title>
   <para>
    As in C or Perl, PHP requires instructions to be terminated
    with a semicolon at the end of each statement. The closing tag
    of a block of PHP code automatically implies a semicolon; you
    do not need to have a semicolon terminating the last line of a
    PHP block. The closing tag for the block will include the immediately
    trailing newline if one is present.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
    echo 'This is a test';
?>

<?php echo 'This is a test' ?>

<?php echo 'We omitted the last closing tag';
]]>
     </programlisting>
    </informalexample>
    <note>
     <para>
      The closing tag of a PHP block at the end of a file is optional,
      and in some cases omitting it is helpful when using <function>include</function>
      or <function>require</function>, so unwanted whitespace will
      not occur at the end of files, and you will still be able to add
      headers to the response later. It is also handy if you use output
      buffering, and would not like to see added unwanted whitespace
      at the end of the parts generated by the included files.
     </para>
    </note>
   </para>
  </sect1>
  <sect1 xml:id="language.basic-syntax.comments">
   <title>Comments</title>
   <para>
    PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
    echo 'This is a test'; // This is a one-line c++ style comment
    /* This is a multi line comment
       yet another line of comment */
    echo 'This is yet another test';
    echo 'One Final Test'; # This is a one-line shell-style comment
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    The "one-line" comment styles only comment to the end of
    the line or the current block of PHP code, whichever comes first.
    This means that HTML code after <literal>// ... ?&gt;</literal>
    or <literal># ...  ?&gt;</literal> WILL be printed:
    ?&gt; breaks out of PHP mode and returns to HTML mode, and
    <literal>//</literal> or <literal>#</literal> cannot influence that.
    If the <link linkend="ini.asp-tags">asp_tags</link> configuration directive
    is enabled, it behaves the same with <literal>// %&gt;</literal> and
    <literal># %&gt;</literal>.
    However, the <literal>&lt;/script&gt;</literal> tag doesn't break out of PHP mode in
    a one-line comment.
   </simpara>
   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
<h1>This is an <?php # echo 'simple';?> example</h1>
<p>The header above will say 'This is an  example'.</p>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    'C' style comments end at the first <literal>*/</literal> encountered.
    Make sure you don't nest 'C' style comments.  It is easy to make this
    mistake if you are trying to comment out a large block of code.
   </simpara>
   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
 /*
    echo 'This is a test'; /* This comment will cause a problem */
 */
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>
 </chapter>

<!-- 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
-->