<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.52 $ -->
<chapter xml:id="language.basic-syntax" xmlns="http://docbook.org/ns/docbook">
<title>Basic syntax</title>
<sect1 xml: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 ?> 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. 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, <?php ?> and
<script language="php"> </script>, 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 <?php ?> 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.
</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.
</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 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>// ... ?></literal>
or <literal># ... ?></literal> WILL be printed:
?> 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>// %></literal> and
<literal># %></literal>.
However, the <literal></script></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
-->