<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->
 <chapter id="language.basic-syntax">
  <title>Basic syntax</title>

   <!--
   
    NOTE:                             Last modified: 2001-05-16 13:00 GMT
    
    the language part is currently under heavy revision. Please do not
    not make any heavy (i.e. structural) modifications to this part 
    for a moment. 
    
    You'd also better not start any translation yet.
    
    Comments are always welcome at phpdoc@lists.php.net
    
    Progress:
    
     intro : DOESN'T EXIST - yet?
             new chapter, with some introductionary remarks?
             Will be discussed on the ML soon.
     basic-syntax: 
             FINISHED
             except maybe moving the 'advanced escaping'
             to a better place?
             TODO: 
              - nada
     types : Being revised. Added all new types
             Boolean and Integer are more or less finished.
             The rest isn't.
             TODO: 
              - why is $foo[bar] bad syntax?
              - what's the difference between unset($bla) and
                $bla = NULL; (it is different!)
              - $obj->{expr} syntax
              - (unset) cast?????
              - $bla = unset <== should've been nuked, don't mention it
              - $str{offset} syntax, rather than $str[offset]
              - read notes and apply when any of them are useful
              - remove notes which have been included here.
              - ...
     the rest: Not yet started with.
             TODO: 
              - ?
     oop   : has been revised by Kristian, DONE.
   -->
   
  <sect1 id="language.basic-syntax.phpmode">
   <title>Escaping from HTML</title>
  
   <para>
    When PHP parses a file, it simply passes the text of the file
    through until it encounters one of the special tags which tell it
    to start interpreting the text as PHP code. The parser then
    executes all the code it finds, up until it runs into a PHP
    closing tag, which tells the parser to just start passing the text
    through again. This is the mechanism which allows you to embed PHP
    code inside HTML: everything outside the PHP tags is left utterly
    alone, while everything inside is parsed as code.
   </para>

   <para>
    There are four sets of tags which can be used to denote blocks of
    PHP code. Of these, only two (&lt;?php. . .?&gt; and &lt;script
    language="php"&gt;. . .&lt;/script&gt;) are always available; the
    others can be turned on or off from the
    <filename>php.ini</filename> configuration file. While the
    short-form tags and ASP-style tags may be convenient, they are not
    as portable as the longer versions. Also, if you intend to embed
    PHP code in XML or XHTML, you will need to use the
    &lt;?php. . .?&gt; form to conform to the XML.
   </para>

   <para>
    The tags supported by PHP are:
   </para>

    <para>
     <example>
      <title>Ways of escaping from HTML</title>
      <programlisting role="php">
<![CDATA[
1.  <? echo ("this is the simplest, an SGML processing instruction\n"); ?>
    <?= expression ?> This is a shortcut for "<? echo expression ?>"
    
2.  <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?>

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

4.  <% echo ("You may optionally use ASP-style tags"); %>
    <%= $variable; # This is a shortcut for "<% echo . . ." %>
]]>
      </programlisting>
     </example>
    </para>

   <para>
    The first way is only available if short tags have been
    enabled. This can be done via the <function>short_tags</function>
    function (PHP 3 only), by enabling the <link
    linkend="ini.short-open-tag">short_open_tag</link> configuration
    setting in the PHP config file, or by compiling PHP with the
    --enable-short-tags option to <command>configure</command>.
   </para>

   <para>
    Again, the second way is the generally preferred method, as it
    allows for the the use of PHP in XML-conformant code such as
    XHTML.
   </para>

   <para>
    The fourth way is only available if ASP-style tags have been
    enabled using the <link linkend="ini.asp-tags">asp_tags</link>
    configuration setting.

    <note>
     <para>Support for ASP-style tags was added in 3.0.4.</para>
    </note>
   </para>

   <para>
    The closing tag for the block will include the immediately
    trailing newline if one is present. Also, the closing tag
    automatically implies a semicolon; you do not need to have a
    semicolon terminating the last line of a PHP block.
   </para>
    
    <para>
    PHP allows you to use structures like this:
    <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> or somesuch.
   </para>
  </sect1>
  
  <sect1 id="language.basic-syntax.instruction-separation">
   <title>Instruction separation</title>
   
   <simpara>
    Instructions are separated the same as in C or Perl - terminate
    each statement with a semicolon.</simpara>

   <para>
    The closing tag (?&gt;) also implies the end of the statement, so
    the following are equivalent:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
    echo "This is a test";
?>

<?php echo "This is a test" ?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="language.basic-syntax.comments">
   <title>Comments</title>
   
   <para>
    PHP supports 'C', 'C++' and Unix shell-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 shell-style style comment
?>
]]>
     </programlisting>
    </informalexample>
   </para>

   <simpara>
    The "one-line" comment styles actually only comment to the end of
    the line or the current block of PHP code, whichever comes
    first.
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<h1>This is an <?php # echo "simple";?> example.</h1>
<p>The header above will say 'This is an example'.
]]>
    </programlisting>
   </informalexample> 

   <simpara>
    You should be careful not to nest 'C' style comments, which can
    happen when commenting out large blocks.
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
 /* 
    echo "This is a test"; /* This comment will cause a problem */
 */
?>
]]>
    </programlisting>
   </informalexample>
  </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
-->