restructured the docbook elements to follow

<this>
 <that>
  <the other>
Rewrote the sections, which were redundant, and added a few more
examples.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@177726 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Derek Ford 2005-01-20 08:42:54 +00:00
parent 807cb5550e
commit 39e467d1b7

View file

@ -1,156 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.39 $ -->
<!-- $Revision: 1.40 $ -->
<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
&php.ini; 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">
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[
1. <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?>
2. <? echo ("this is the simplest, an SGML processing instruction\n"); ?>
<?= expression ?> This is a shortcut for "<? echo expression ?>"
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 . . ." %>
<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>
</example>
</para>
<para>
The first way, &lt;?php. . .?&gt;, is the preferred method, as it
allows the use of PHP in XML-conformant code such as XHTML.
</programlisting>
</informalexample>
</para>
<para>
The second way is not available always. Short tags are available
only when they 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 <option>--enable-short-tags</option> option to
<command>configure</command>. Even if it is enabled by default in
<filename>php.ini-dist</filename>, use of short tags are discouraged.
</para>
<para>
The third way is always available and safe like the first one. However,
the first is the preferred and most used one.
</para>
<para>
The fourth way is only available if <productname>ASP</productname>
tags have been enabled using the <link linkend="ini.asp-tags">asp_tags</link>
configuration setting.
<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>
<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.
Closing tag of a PHP block at the end of a file is optional.
</para>
<para>
PHP allows you to use structures like this:
<example><title>Advanced escaping</title>
You can also use more advanced structures:
<example>
<title>Advanced escaping</title>
<programlisting role="php">
<![CDATA[
<?php
@ -173,22 +48,95 @@ if ($expression) {
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.
<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\n"); ?>
2. <? echo ("this is the simplest, an SGML processing instruction\n"); ?>
<?= expression ?> This is a shortcut for "<? echo expression ?>"
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>
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>
<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:
As in C or Perl, PHP requires instructions to be separated
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[
@ -200,14 +148,19 @@ if ($expression) {
]]>
</programlisting>
</informalexample>
</para>
<note>
<para>
The closing tag of a PHP block at the end of a file is optional,
and in some cases is helpful when using output buffering and
<function>include</function> or <function>require</function>.
</para>
</note>
</para>
</sect1>
<sect1 id="language.basic-syntax.comments">
<title>Comments</title>
<title>Comments</title>
<para>
PHP supports 'C', 'C++' and Unix shell-style comments. For example:
PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:
<informalexample>
<programlisting role="php">
@ -223,11 +176,14 @@ if ($expression) {
</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.
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> WILL be printed:
?&gt; skips out of the PHP mode and returns to HTML mode, and
<literal>//</literal> cannot influence that.
If <link linkend="ini.asp-tags">asp_tags</link> configuration directive
is enabled, it behaves the same with <literal>// %&gt;</literal>.
</simpara>
<para>
<informalexample>
@ -239,13 +195,11 @@ if ($expression) {
</programlisting>
</informalexample>
</para>
<simpara>
'C' style comments end by the first encountered <literal>*/</literal>.
You should be careful not to nest 'C' style comments, which can
happen when commenting out large blocks.
</simpara>
<para>
<informalexample>
<programlisting role="php">
@ -259,16 +213,6 @@ if ($expression) {
</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.
This means that HTML code after <literal>// ?&gt;</literal> WILL be printed:
?&gt; skips out of the PHP mode and returns to HTML mode, and
<literal>//</literal> cannot influence that.
If <link linkend="ini.asp-tags">asp_tags</link> configuration directive
is enabled, it behaves the same with <literal>// %&gt;</literal>.
</simpara>
</sect1>
</chapter>