<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.49 $ -->
 <chapter id="language.basic-syntax">
  <title>Basic syntax</title>
  <sect1 id="language.basic-syntax.phpmode">
   <title>Escaping from HTML</title>
   <para>
    When PHP parses a file, it looks for opening and closing tags, 
    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. 
    Most of the time you will see php embedded in HTML documents, 
    as in this example.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<p>This is going to be ignored.</p>
<?php echo 'While this is going to be parsed.'; ?>
<p>This will also be ignored.</p>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    You can also use more advanced structures:
    <example>
     <title>Advanced escaping</title>
     <programlisting role="php">
<![CDATA[
<?php
if ($expression) { 
    ?>
    <strong>This is true.</strong>
    <?php 
} else { 
    ?>
    <strong>This is false.</strong>
    <?php 
}
?>
]]>
     </programlisting>
    </example>
    This works as expected, because when PHP hits the ?&gt; closing
    tags, it simply starts outputting whatever it finds until it hits
    another opening tag. The example given here is contrived, of
    course, but 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>
    There are four different pairs of opening and closing tags 
    which can be used in php. Two of those, &lt;?php ?&gt; and 
    &lt;script language="php"&gt; &lt;/script&gt;, are always available.
    The other two are short tags and <productname>ASP</productname> 
    style tags, and can be turned on and off from the &php.ini; 
    configuration file. 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>
    <example>
     <title>PHP Opening and Closing Tags</title>
     <programlisting role="php">
<![CDATA[
1.  <?php echo 'if you want to serve XHTML or XML documents, do like this'; ?>

2.  <script language="php">
        echo 'some editors (like FrontPage) don\'t
              like processing instructions';
    </script>

3.  <? echo 'this is the simplest, an SGML processing instruction'; ?>
    <?= expression ?> This is a shortcut for "<? echo expression ?>"

4.  <% echo 'You may optionally use ASP-style tags'; %>
    <%= $variable; # This is a shortcut for "<% echo . . ." %>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    While the tags seen in examples one and two are both 
    always available, example one is the most commonly 
    used, and recommended, of the two. 
   </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.
    <note>
     <para>
      If you are using PHP 3 you may also enable short tags via 
      the <function>short_tags</function> function. <emphasis>This 
      is only available in PHP 3!</emphasis>
     </para>
    </note>
   </para>    
   <para>
    <productname>ASP</productname> style tags (example four) are only available when 
    they are enabled via the <link linkend="ini.asp-tags">asp_tags</link> &php.ini;
    configuration file directive.
    <note>
     <para>
      Support for <productname>ASP</productname> tags was added in 3.0.4.
     </para>
    </note>
   </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>
   </para>
  </sect1>
  <sect1 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 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:"../../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
-->