language/basic-syntax.xml
0e618211e53c66f33762be225a4d57c08ef4b2f7
0e618211e53c66f33762be225a4d57c08ef4b2f7
...
...
@@ -1,53 +1,97 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<chapter xml:id="language.basic-syntax" xmlns="http://docbook.org/ns/docbook">
3
+
<chapter xml:id="language.basic-syntax" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
4
4
<title>Basic syntax</title>
5
5
<sect1 xml:id="language.basic-syntax.phptags">
6
6
<title>PHP tags</title>
7
7
<para>
8
-
When PHP parses a file, it looks for opening and closing tags,
9
-
which are <literal><?php</literal> and <literal>?></literal>
10
-
which tell PHP to start and stop interpreting the code between
11
-
them. Parsing in this manner allows PHP to be embedded in all
12
-
sorts of different documents, as everything outside of a pair
13
-
of opening and closing tags is ignored by the PHP parser.
8
+
When PHP processes a file, it recognizes the opening and closing
9
+
tags, <literal><?php</literal> and <literal>?></literal>, to
10
+
define the boundaries of PHP code execution. Content outside these
11
+
tags is ignored by the PHP parser, allowing PHP to seamlessly embed
12
+
in various document types.
14
13
</para>
14
+
15
15
<para>
16
-
PHP also allows for short open tag <literal><?</literal>
17
-
(which is discouraged since it is only available if enabled using the
18
-
<link linkend="ini.short-open-tag">short_open_tag</link> &php.ini; configuration
19
-
file directive, or if PHP was configured with the <option>--enable-short-tags</option>
20
-
option).
16
+
A whitespace character (space, tab, or newline) must follow
17
+
<literal><?php</literal> to ensure proper token separation.
18
+
Omitting this whitespace will result in a syntax error.
21
19
</para>
20
+
22
21
<para>
23
-
If a file is pure PHP code, it is preferable to omit the PHP closing tag at the
24
-
end of the file. This prevents accidental whitespace or new lines being added after the PHP
25
-
closing tag, which may cause unwanted effects because PHP will start output
26
-
buffering when there is no intention from the programmer to send any output
27
-
at that point in the script.
28
-
<informalexample>
22
+
PHP also includes the short echo tag <literal><?=</literal>,
23
+
which is shorthand for <code><?php echo</code>.
24
+
</para>
25
+
<para>
26
+
<example>
27
+
<title>PHP Opening and Closing Tags</title>
28
+
<programlisting role="php">
29
+
<![CDATA[
30
+
1. <?php echo 'if you want to serve PHP code in XHTML or XML documents,
31
+
use these tags'; ?>
32
+
33
+
2. You can use the short echo tag to <?= 'print this string' ?>.
34
+
It's equivalent to <?php echo 'print this string' ?>.
35
+
36
+
3. <? echo 'this code is within short tags, but will only work '.
37
+
'if short_open_tag is enabled'; ?>
38
+
]]>
39
+
</programlisting>
40
+
</example>
41
+
</para>
42
+
43
+
<para>
44
+
Short tags (example three) are available by default but can be disabled
45
+
either via the <link linkend="ini.short-open-tag">short_open_tag</link>
46
+
&php.ini; configuration file directive, or are disabled by default if
47
+
PHP is built with the <option>--disable-short-tags</option> configuration.
48
+
</para>
49
+
<para>
50
+
<note>
51
+
<para>
52
+
As short tags can be disabled it is recommended to only use the normal
53
+
tags (<code><?php ?></code> and <code><?= ?></code>) to
54
+
maximise compatibility.
55
+
</para>
56
+
</note>
57
+
</para>
58
+
59
+
<para>
60
+
If a file ends with PHP code, it is preferable to omit the PHP closing tag
61
+
at the end of the file. This prevents accidental whitespace or new lines
62
+
being added after the PHP closing tag, which may cause unwanted effects
63
+
because PHP will start output buffering when there is no intention from
64
+
the programmer to send any output at that point in the script.
65
+
</para>
66
+
<para>
67
+
<example>
68
+
<title>PHP Code Only File</title>
29
69
<programlisting role="php">
30
70
<![CDATA[
31
71
<?php
32
-
echo "Hello world";
72
+
echo "Hello world\n";
33
73
34
74
// ... more code
35
75
36
-
echo "Last statement";
76
+
echo "Last statement\n";
37
77
38
78
// the script ends here with no PHP closing tag
39
79
]]>
40
80
</programlisting>
41
-
</informalexample>
81
+
</example>
42
82
</para>
43
83
</sect1>
84
+
44
85
<sect1 xml:id="language.basic-syntax.phpmode">
45
86
<title>Escaping from HTML</title>
46
87
<para>
47
88
Everything outside of a pair of opening and closing tags is ignored by the
48
-
PHP parser which allows PHP files to have mixed content. This allows PHP
89
+
PHP parser which allows PHP files to have mixed content. This allows PHP
49
90
to be embedded in HTML documents, for example to create templates.
91
+
</para>
92
+
<para>
50
93
<example>
94
+
<title>Embedding PHP in HTML</title>
51
95
<programlisting role="php">
52
96
<![CDATA[
53
97
<p>This is going to be ignored by PHP and displayed by the browser.</p>
...
...
@@ -56,8 +100,10 @@ echo "Last statement";
56
100
]]>
57
101
</programlisting>
58
102
</example>
103
+
</para>
104
+
<para>
59
105
This works as expected, because when the PHP interpreter hits the ?> closing
60
-
tags, it simply starts outputting whatever it finds (except for an
106
+
tags, it simply starts outputting whatever it finds (except for the
61
107
immediately following newline - see
62
108
<link linkend="language.basic-syntax.instruction-separation">instruction separation</link>)
63
109
until it hits another opening tag unless in the middle of a conditional
...
...
@@ -80,9 +126,9 @@ echo "Last statement";
80
126
</programlisting>
81
127
</example>
82
128
In this example PHP will skip the blocks where the condition is not met, even
83
-
though they are outside of the PHP open/close tags, PHP skips them according
129
+
though they are outside of the PHP open/close tags; PHP skips them according
84
130
to the condition since the PHP interpreter will jump over blocks contained
85
-
within a condition what is not met.
131
+
within a condition that is not met.
86
132
</para>
87
133
<para>
88
134
For outputting large blocks of text, dropping out of PHP parsing mode is
...
...
@@ -90,86 +136,16 @@ echo "Last statement";
90
136
<function>echo</function> or <function>print</function>.
91
137
</para>
92
138
<para>
93
-
There are four different pairs of opening and closing tags
94
-
which can be used in PHP. Two of those, <?php ?> and
95
-
<script language="php"> </script>, are always available.
96
-
The other two are short tags and <productname>ASP</productname>
97
-
style tags, and can be turned on and off from the &php.ini;
98
-
configuration file. As such, while some people find short tags
99
-
and <productname>ASP</productname> style tags convenient, they
100
-
are less portable, and generally not recommended.
101
-
<note>
102
-
<para>
103
-
Also note that if you are embedding PHP within XML or XHTML
104
-
you will need to use the <?php ?> tags to remain
105
-
compliant with standards.
106
-
</para>
107
-
</note>
108
-
</para>
109
-
<para>
110
-
<example>
111
-
<title>PHP Opening and Closing Tags</title>
112
-
<programlisting role="php">
113
-
<![CDATA[
114
-
1. <?php echo 'if you want to serve PHP code in XHTML or XML documents,
115
-
use these tags'; ?>
116
-
117
-
2. <script language="php">
118
-
echo 'some editors (like FrontPage) don\'t
119
-
like processing instructions within these tags';
120
-
</script>
121
-
122
-
3. <? echo 'this code is within short tags'; ?>
123
-
Code within these tags <?= 'some text' ?> is a shortcut for this code <? echo 'some text' ?>
124
-
125
-
4. <% echo 'You may optionally use ASP-style tags'; %>
126
-
Code within these tags <%= $variable; %> is a shortcut for this code <% echo $variable; %>
127
-
]]>
128
-
</programlisting>
129
-
</example>
130
-
</para>
131
-
<para>
132
-
While the tags seen in examples one and two are both
133
-
always available, example one is the most commonly
134
-
used, and recommended, of the two.
135
-
</para>
136
-
<para>
137
-
Short tags (example three) are only available when they are
138
-
enabled via the <link linkend="ini.short-open-tag">short_open_tag</link>
139
-
&php.ini; configuration file directive, or if PHP was configured
140
-
with the <option>--enable-short-tags</option> option.
141
-
</para>
142
-
<para>
143
-
<productname>ASP</productname> style tags (example four) are only available when
144
-
they are enabled via the <link linkend="ini.asp-tags">asp_tags</link> &php.ini;
145
-
configuration file directive.
146
-
</para>
147
-
<para>
148
-
<note>
149
-
<para>
150
-
Using short tags should be avoided when developing applications
151
-
or libraries that are meant for redistribution, or deployment on
152
-
PHP servers which are not under your control, because short tags
153
-
may not be supported on the target server. For portable,
154
-
redistributable code, be sure not to use short tags.
155
-
</para>
156
-
</note>
157
-
<note>
158
-
<para>
159
-
In PHP 5.2 and earlier, the parser does not allow the
160
-
<literal><?php</literal> opening tag to be the only thing in a file.
161
-
This is allowed as of PHP 5.3 provided there are one or more whitespace
162
-
characters after the opening tag.
163
-
</para>
164
-
</note>
165
139
<note>
166
140
<para>
167
-
Starting with PHP 5.4, short echo tag <literal><?=</literal> is always recognized and
168
-
valid, regardless of the <link linkend="ini.short-open-tag">short_open_tag</link> setting.
141
+
If PHP is embeded within XML or XHTML the normal PHP
142
+
<code><?php ?></code> must be used to remain compliant
143
+
with the standards.
169
144
</para>
170
145
</note>
171
146
</para>
172
147
</sect1>
148
+
173
149
<sect1 xml:id="language.basic-syntax.instruction-separation">
174
150
<title>Instruction separation</title>
175
151
<para>
...
...
@@ -179,19 +155,45 @@ echo "Last statement";
179
155
do not need to have a semicolon terminating the last line of a
180
156
PHP block. The closing tag for the block will include the immediately
181
157
trailing newline if one is present.
182
-
<informalexample>
158
+
</para>
159
+
160
+
<para>
161
+
<example>
162
+
<title>Example showing the closing tag encompassing the trailing newline</title>
163
+
<programlisting role="php">
164
+
<![CDATA[
165
+
<?php echo "Some text"; ?>
166
+
No newline
167
+
<?= "But newline now" ?>
168
+
]]>
169
+
</programlisting>
170
+
&example.outputs;
171
+
<screen>
172
+
<![CDATA[
173
+
Some textNo newline
174
+
But newline now
175
+
]]>
176
+
</screen>
177
+
</example>
178
+
</para>
179
+
180
+
<para>
181
+
<example>
182
+
<title>Examples of entering and exiting the PHP parser</title>
183
183
<programlisting role="php">
184
184
<![CDATA[
185
185
<?php
186
-
echo 'This is a test';
186
+
echo "This is a test\n";
187
187
?>
188
188
189
-
<?php echo 'This is a test' ?>
189
+
<?php echo "This is a test\n" ?>
190
190
191
-
<?php echo 'We omitted the last closing tag';
191
+
<?php echo "We omitted the last closing tag\n";
192
192
]]>
193
193
</programlisting>
194
-
</informalexample>
194
+
</example>
195
+
</para>
196
+
<para>
195
197
<note>
196
198
<para>
197
199
The closing tag of a PHP block at the end of a file is optional,
...
...
@@ -209,20 +211,22 @@ echo "Last statement";
209
211
<title>Comments</title>
210
212
<para>
211
213
PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:
212
-
213
-
<informalexample>
214
+
</para>
215
+
<para>
216
+
<example>
217
+
<title>Comments</title>
214
218
<programlisting role="php">
215
219
<![CDATA[
216
220
<?php
217
-
echo 'This is a test'; // This is a one-line c++ style comment
221
+
echo "This is a test\n"; // This is a one-line c++ style comment
218
222
/* This is a multi line comment
219
223
yet another line of comment */
220
-
echo 'This is yet another test';
221
-
echo 'One Final Test'; # This is a one-line shell-style comment
224
+
echo "This is yet another test\n";
225
+
echo "One Final Test\n"; # This is a one-line shell-style comment
222
226
?>
223
227
]]>
224
228
</programlisting>
225
-
</informalexample>
229
+
</example>
226
230
</para>
227
231
<simpara>
228
232
The "one-line" comment styles only comment to the end of
...
...
@@ -231,25 +235,21 @@ echo "Last statement";
231
235
or <literal># ... ?></literal> WILL be printed:
232
236
?> breaks out of PHP mode and returns to HTML mode, and
233
237
<literal>//</literal> or <literal>#</literal> cannot influence that.
234
-
If the <link linkend="ini.asp-tags">asp_tags</link> configuration directive
235
-
is enabled, it behaves the same with <literal>// %></literal> and
236
-
<literal># %></literal>.
237
-
However, the <literal></script></literal> tag doesn't break out of PHP mode in
238
-
a one-line comment.
239
238
</simpara>
240
239
<para>
241
-
<informalexample>
240
+
<example>
241
+
<title>One Line Comments</title>
242
242
<programlisting role="php">
243
243
<![CDATA[
244
244
<h1>This is an <?php # echo 'simple';?> example</h1>
245
245
<p>The header above will say 'This is an example'.</p>
246
246
]]>
247
247
</programlisting>
248
-
</informalexample>
248
+
</example>
249
249
</para>
250
250
<simpara>
251
251
'C' style comments end at the first <literal>*/</literal> encountered.
252
-
Make sure you don't nest 'C' style comments. It is easy to make this
252
+
Make sure you don't nest 'C' style comments. It is easy to make this
253
253
mistake if you are trying to comment out a large block of code.
254
254
</simpara>
255
255
<para>
256
256