mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
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
parent
807cb5550e
commit
39e467d1b7
1 changed files with 119 additions and 175 deletions
|
|
@ -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 (<?php. . .?> and <script
|
||||
language="php">. . .</script>) 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
|
||||
<?php. . .?> 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, <?php. . .?>, 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, <?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\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 (?>) 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>// ?></literal> WILL be printed:
|
||||
?> 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>// %></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>// ?></literal> WILL be printed:
|
||||
?> 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>// %></literal>.
|
||||
</simpara>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue