language/basic-syntax.xml
0e618211e53c66f33762be225a4d57c08ef4b2f7
...
...
@@ -1,59 +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, which are
9
-
<literal>&lt;?php</literal> and <literal>?&gt;</literal> which tell PHP to
10
-
start and stop interpreting the code between them. Parsing in this manner
11
-
allows PHP to be embedded in all sorts of different documents, as
12
-
everything outside of a pair of opening and closing tags is ignored by the
13
-
PHP parser.
8
+
When PHP processes a file, it recognizes the opening and closing
9
+
tags, <literal>&lt;?php</literal> and <literal>?&gt;</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>
15
14

16
15
<para>
17
-
PHP includes a short echo tag <literal>&lt;?=</literal> which is a
18
-
short-hand to the more verbose <code>&lt;?php echo</code>.
16
+
A whitespace character (space, tab, or newline) must follow
17
+
<literal>&lt;?php</literal> to ensure proper token separation.
18
+
Omitting this whitespace will result in a syntax error.
19
19
</para>
20
20

21
21
<para>
22
-
PHP also allows for short open tag <literal>&lt;?</literal> (which is
23
-
discouraged since it is only available if enabled using the
24
-
<link linkend="ini.short-open-tag">short_open_tag</link> &php.ini;
25
-
configuration file directive, or if PHP was configured with the
26
-
<option>--enable-short-tags</option> option).
22
+
PHP also includes the short echo tag <literal>&lt;?=</literal>,
23
+
which is shorthand for <code>&lt;?php echo</code>.
27
24
</para>
28
25
<para>
29
-
If a file contains only PHP code, it is preferable to omit the PHP closing tag
30
-
at the end of the file. This prevents accidental whitespace or new lines
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>&lt;?php ?&gt;</code> and <code>&lt;?= ?&gt;</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
31
62
being added after the PHP closing tag, which may cause unwanted effects
32
63
because PHP will start output buffering when there is no intention from
33
64
the programmer to send any output at that point in the script.
34
-
<informalexample>
65
+
</para>
66
+
<para>
67
+
<example>
68
+
<title>PHP Code Only File</title>
35
69
<programlisting role="php">
36
70
<![CDATA[
37
71
<?php
38
-
echo "Hello world";
72
+
echo "Hello world\n";
39
73

40
74
// ... more code
41
75

42
-
echo "Last statement";
76
+
echo "Last statement\n";
43
77

44
78
// the script ends here with no PHP closing tag
45
79
]]>
46
80
</programlisting>
47
-
</informalexample>
81
+
</example>
48
82
</para>
49
83
</sect1>
84
+

50
85
<sect1 xml:id="language.basic-syntax.phpmode">
51
86
<title>Escaping from HTML</title>
52
87
<para>
53
88
Everything outside of a pair of opening and closing tags is ignored by the
54
-
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
55
90
to be embedded in HTML documents, for example to create templates.
56
-
<informalexample>
91
+
</para>
92
+
<para>
93
+
<example>
94
+
<title>Embedding PHP in HTML</title>
57
95
<programlisting role="php">
58
96
<![CDATA[
59
97
<p>This is going to be ignored by PHP and displayed by the browser.</p>
...
...
@@ -61,9 +99,11 @@ echo "Last statement";
61
99
<p>This will also be ignored by PHP and displayed by the browser.</p>
62
100
]]>
63
101
</programlisting>
64
-
</informalexample>
102
+
</example>
103
+
</para>
104
+
<para>
65
105
This works as expected, because when the PHP interpreter hits the ?&gt; closing
66
-
tags, it simply starts outputting whatever it finds (except for an
106
+
tags, it simply starts outputting whatever it finds (except for the
67
107
immediately following newline - see
68
108
<link linkend="language.basic-syntax.instruction-separation">instruction separation</link>)
69
109
until it hits another opening tag unless in the middle of a conditional
...
...
@@ -95,52 +135,17 @@ echo "Last statement";
95
135
generally more efficient than sending all of the text through
96
136
<function>echo</function> or <function>print</function>.
97
137
</para>
98
-
<para>
99
-
There is also the short echo tag <code>&lt;?= ?&gt;</code>.
100
-
</para>
101
-
<para>
102
-
<note>
103
-
<para>
104
-
Also note that if you are embedding PHP within XML or XHTML
105
-
you will need to use the &lt;?php ?&gt; tags to remain
106
-
compliant with standards.
107
-
</para>
108
-
</note>
109
-
</para>
110
-

111
-
<para>
112
-
<example>
113
-
<title>PHP Opening and Closing Tags</title>
114
-
<programlisting role="php">
115
-
<![CDATA[
116
-
1. <?php echo 'if you want to serve PHP code in XHTML or XML documents,
117
-
use these tags'; ?>
118
-

119
-
2. You can use the short echo tag to <?= 'print this string' ?>.
120
-
It's equivalent to <?php echo 'print this string' ?>.
121
-

122
-
3. <? echo 'this code is within short tags, but will only work '.
123
-
'if short_open_tag is enabled'; ?>
124
-
]]>
125
-
</programlisting>
126
-
</example>
127
-
</para>
128
-
<para>
129
-
Short tags (example three) are available by default but can be disabled
130
-
either via the <link linkend="ini.short-open-tag">short_open_tag</link>
131
-
&php.ini; configuration file directive, or are disabled by default if
132
-
PHP is built with the <option>--disable-short-tags</option> configuration.
133
-
</para>
134
138
<para>
135
139
<note>
136
140
<para>
137
-
As short tags can be disabled it is recommened to only use the normal
138
-
tags (<code>&lt;?php ?&gt;</code> and <code>&lt;?= ?&gt;</code>) to
139
-
maximise compatibility.
141
+
If PHP is embeded within XML or XHTML the normal PHP
142
+
<code>&lt;?php ?&gt;</code> must be used to remain compliant
143
+
with the standards.
140
144
</para>
141
145
</note>
142
146
</para>
143
147
</sect1>
148
+

144
149
<sect1 xml:id="language.basic-syntax.instruction-separation">
145
150
<title>Instruction separation</title>
146
151
<para>
...
...
@@ -150,19 +155,45 @@ echo "Last statement";
150
155
do not need to have a semicolon terminating the last line of a
151
156
PHP block. The closing tag for the block will include the immediately
152
157
trailing newline if one is present.
153
-
<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>
154
183
<programlisting role="php">
155
184
<![CDATA[
156
185
<?php
157
-
echo 'This is a test';
186
+
echo "This is a test\n";
158
187
?>
159
188

160
-
<?php echo 'This is a test' ?>
189
+
<?php echo "This is a test\n" ?>
161
190

162
-
<?php echo 'We omitted the last closing tag';
191
+
<?php echo "We omitted the last closing tag\n";
163
192
]]>
164
193
</programlisting>
165
-
</informalexample>
194
+
</example>
195
+
</para>
196
+
<para>
166
197
<note>
167
198
<para>
168
199
The closing tag of a PHP block at the end of a file is optional,
...
...
@@ -180,20 +211,22 @@ echo "Last statement";
180
211
<title>Comments</title>
181
212
<para>
182
213
PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:
183
-

184
-
<informalexample>
214
+
</para>
215
+
<para>
216
+
<example>
217
+
<title>Comments</title>
185
218
<programlisting role="php">
186
219
<![CDATA[
187
220
<?php
188
-
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
189
222
/* This is a multi line comment
190
223
yet another line of comment */
191
-
echo 'This is yet another test';
192
-
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
193
226
?>
194
227
]]>
195
228
</programlisting>
196
-
</informalexample>
229
+
</example>
197
230
</para>
198
231
<simpara>
199
232
The "one-line" comment styles only comment to the end of
...
...
@@ -204,18 +237,19 @@ echo "Last statement";
204
237
<literal>//</literal> or <literal>#</literal> cannot influence that.
205
238
</simpara>
206
239
<para>
207
-
<informalexample>
240
+
<example>
241
+
<title>One Line Comments</title>
208
242
<programlisting role="php">
209
243
<![CDATA[
210
244
<h1>This is an <?php # echo 'simple';?> example</h1>
211
245
<p>The header above will say 'This is an example'.</p>
212
246
]]>
213
247
</programlisting>
214
-
</informalexample>
248
+
</example>
215
249
</para>
216
250
<simpara>
217
251
'C' style comments end at the first <literal>*/</literal> encountered.
218
-
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
219
253
mistake if you are trying to comment out a large block of code.
220
254
</simpara>
221
255
<para>
222
256