mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
274 lines
8.5 KiB
XML
274 lines
8.5 KiB
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><?php</literal> and <literal>?></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 includes a short echo tag <literal><?=</literal> which is a
|
|
short-hand to the more verbose <code><?php echo</code>.
|
|
</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 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'; ?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
Short tags (example three) are available by default but can be disabled
|
|
either via the <link linkend="ini.short-open-tag">short_open_tag</link>
|
|
&php.ini; configuration file directive, or are disabled by default if
|
|
PHP is built with the <option>--disable-short-tags</option> configuration.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
As short tags can be disabled it is recommended to only use the normal
|
|
tags (<code><?php ?></code> and <code><?= ?></code>) to
|
|
maximise compatibility.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
|
|
<para>
|
|
If a file contains only 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>
|
|
</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.
|
|
<informalexample>
|
|
<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>
|
|
</informalexample>
|
|
This works as expected, because when the PHP interpreter hits the ?> closing
|
|
tags, it simply starts outputting whatever it finds (except for the
|
|
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 that 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>
|
|
<note>
|
|
<para>
|
|
If PHP is embeded within XML or XHTML the normal PHP
|
|
<code><?php ?></code> must be used to remain compliant
|
|
with the standards.
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Example showing the closing tag encompassing the trailing newline</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php echo "Some text"; ?>
|
|
No newline
|
|
<?= "But newline now" ?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Some textNo newline
|
|
But newline now
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
Examples of entering and exiting the PHP parser:
|
|
|
|
<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.
|
|
</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
|
|
-->
|