language/basic-syntax.xml
0e618211e53c66f33762be225a4d57c08ef4b2f7
0e618211e53c66f33762be225a4d57c08ef4b2f7
...
...
@@ -1,82 +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><?php</literal> and <literal>?></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><?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
+
<para>
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.
19
+
</para>
20
+
21
+
<para>
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
+
15
43
<para>
16
-
PHP also allows for short open tag <literal><?</literal> (which is
17
-
discouraged since it is only available if enabled using the
18
-
<link linkend="ini.short-open-tag">short_open_tag</link> &php.ini;
19
-
configuration file directive, or if PHP was configured with the
20
-
<option>--enable-short-tags</option> option).
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.
21
48
</para>
22
49
<para>
23
-
If a file contains only PHP code, it is preferable to omit the PHP closing tag
24
-
at the end of the file. This prevents accidental whitespace or new lines
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
25
62
being added after the PHP closing tag, which may cause unwanted effects
26
63
because PHP will start output buffering when there is no intention from
27
64
the programmer to send any output at that point in the script.
28
-
<informalexample>
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>
42
-
</para>
43
-
<para>
44
-
<table>
45
-
&reftitle.changelog;
46
-
<tgroup cols="2">
47
-
<thead>
48
-
<row>
49
-
<entry>&Version;</entry>
50
-
<entry>&Description;</entry>
51
-
</row>
52
-
</thead>
53
-
<tbody>
54
-
<row>
55
-
<entry>7.0.0</entry>
56
-
<entry>
57
-
The ASP tags <code><%</code>, <code>%></code>,
58
-
<code><%=</code>, and the script tag
59
-
<code><script language="php"></code> are removed from PHP.
60
-
</entry>
61
-
</row>
62
-
<row>
63
-
<entry>5.4.0</entry>
64
-
<entry>
65
-
The tag <?= is always available regardless of the short_open_tag ini setting.
66
-
</entry>
67
-
</row>
68
-
</tbody>
69
-
</tgroup>
70
-
</table>
81
+
</example>
71
82
</para>
72
83
</sect1>
84
+
73
85
<sect1 xml:id="language.basic-syntax.phpmode">
74
86
<title>Escaping from HTML</title>
75
87
<para>
76
88
Everything outside of a pair of opening and closing tags is ignored by the
77
-
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
78
90
to be embedded in HTML documents, for example to create templates.
79
-
<informalexample>
91
+
</para>
92
+
<para>
93
+
<example>
94
+
<title>Embedding PHP in HTML</title>
80
95
<programlisting role="php">
81
96
<![CDATA[
82
97
<p>This is going to be ignored by PHP and displayed by the browser.</p>
...
...
@@ -84,9 +99,11 @@ echo "Last statement";
84
99
<p>This will also be ignored by PHP and displayed by the browser.</p>
85
100
]]>
86
101
</programlisting>
87
-
</informalexample>
102
+
</example>
103
+
</para>
104
+
<para>
88
105
This works as expected, because when the PHP interpreter hits the ?> closing
89
-
tags, it simply starts outputting whatever it finds (except for an
106
+
tags, it simply starts outputting whatever it finds (except for the
90
107
immediately following newline - see
91
108
<link linkend="language.basic-syntax.instruction-separation">instruction separation</link>)
92
109
until it hits another opening tag unless in the middle of a conditional
...
...
@@ -119,120 +136,64 @@ echo "Last statement";
119
136
<function>echo</function> or <function>print</function>.
120
137
</para>
121
138
<para>
122
-
In PHP 5, there are up to five different pairs of opening and closing tags
123
-
available in PHP, depending on how PHP is configured. Two of these,
124
-
<code><?php ?></code> and
125
-
<code><script language="php"> </script></code>, are always
126
-
available. There is also the short echo tag <code><?= ?></code>,
127
-
which is always available in PHP 5.4.0 and later.
128
-
</para>
129
-
<para>
130
-
The other two are short tags and <productname>ASP</productname> style
131
-
tags. As such, while some people find short tags and
132
-
<productname>ASP</productname> style tags convenient, they are less
133
-
portable, and generally not recommended.
134
139
<note>
135
140
<para>
136
-
Also note that if you are embedding PHP within XML or XHTML
137
-
you will need to use the <?php ?> tags to remain
138
-
compliant with standards.
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.
139
144
</para>
140
145
</note>
141
146
</para>
147
+
</sect1>
148
+
149
+
<sect1 xml:id="language.basic-syntax.instruction-separation">
150
+
<title>Instruction separation</title>
142
151
<para>
143
-
PHP 7 removes support for <productname>ASP</productname> tags and
144
-
<code><script language="php"></code> tags. As such, we recommend
145
-
only using <code><?php ?></code> and <code><?= ?></code> when
146
-
writing PHP code to maximise compatibility.
152
+
As in C or Perl, PHP requires instructions to be terminated
153
+
with a semicolon at the end of each statement. The closing tag
154
+
of a block of PHP code automatically implies a semicolon; you
155
+
do not need to have a semicolon terminating the last line of a
156
+
PHP block. The closing tag for the block will include the immediately
157
+
trailing newline if one is present.
147
158
</para>
159
+
148
160
<para>
149
161
<example>
150
-
<title>PHP Opening and Closing Tags</title>
162
+
<title>Example showing the closing tag encompassing the trailing newline</title>
151
163
<programlisting role="php">
152
164
<![CDATA[
153
-
1. <?php echo 'if you want to serve PHP code in XHTML or XML documents,
154
-
use these tags'; ?>
155
-
156
-
2. You can use the short echo tag to <?= 'print this string' ?>.
157
-
It's always enabled in PHP 5.4.0 and later, and is equivalent to
158
-
<?php echo 'print this string' ?>.
159
-
160
-
3. <? echo 'this code is within short tags, but will only work '.
161
-
'if short_open_tag is enabled'; ?>
162
-
163
-
4. <script language="php">
164
-
echo 'some editors (like FrontPage) don\'t
165
-
like processing instructions within these tags';
166
-
</script>
167
-
This syntax is removed in PHP 7.0.0.
168
-
169
-
5. <% echo 'You may optionally use ASP-style tags'; %>
170
-
Code within these tags <%= $variable; %> is a shortcut for this code <% echo $variable; %>
171
-
Both of these syntaxes are removed in PHP 7.0.0.
165
+
<?php echo "Some text"; ?>
166
+
No newline
167
+
<?= "But newline now" ?>
172
168
]]>
173
169
</programlisting>
170
+
&example.outputs;
171
+
<screen>
172
+
<![CDATA[
173
+
Some textNo newline
174
+
But newline now
175
+
]]>
176
+
</screen>
174
177
</example>
175
178
</para>
179
+
176
180
<para>
177
-
Short tags (example three) are only available when they are
178
-
enabled via the <link linkend="ini.short-open-tag">short_open_tag</link>
179
-
&php.ini; configuration file directive, or if PHP was configured
180
-
with the <option>--enable-short-tags</option> option.
181
-
</para>
182
-
<para>
183
-
<productname>ASP</productname> style tags (example five) are only
184
-
available when they are enabled via the
185
-
<link linkend="ini.asp-tags">asp_tags</link> &php.ini; configuration file
186
-
directive, and have been removed in PHP 7.0.0.
187
-
</para>
188
-
<para>
189
-
<note>
190
-
<para>
191
-
Using short tags should be avoided when developing applications
192
-
or libraries that are meant for redistribution, or deployment on
193
-
PHP servers which are not under your control, because short tags
194
-
may not be supported on the target server. For portable,
195
-
redistributable code, be sure not to use short tags.
196
-
</para>
197
-
</note>
198
-
<note>
199
-
<para>
200
-
In PHP 5.2 and earlier, the parser does not allow the
201
-
<literal><?php</literal> opening tag to be the only thing in a file.
202
-
This is allowed as of PHP 5.3 provided there are one or more whitespace
203
-
characters after the opening tag.
204
-
</para>
205
-
</note>
206
-
<note>
207
-
<para>
208
-
Starting with PHP 5.4, short echo tag <literal><?=</literal> is always recognized and
209
-
valid, regardless of the <link linkend="ini.short-open-tag">short_open_tag</link> setting.
210
-
</para>
211
-
</note>
212
-
</para>
213
-
</sect1>
214
-
<sect1 xml:id="language.basic-syntax.instruction-separation">
215
-
<title>Instruction separation</title>
216
-
<para>
217
-
As in C or Perl, PHP requires instructions to be terminated
218
-
with a semicolon at the end of each statement. The closing tag
219
-
of a block of PHP code automatically implies a semicolon; you
220
-
do not need to have a semicolon terminating the last line of a
221
-
PHP block. The closing tag for the block will include the immediately
222
-
trailing newline if one is present.
223
-
<informalexample>
181
+
<example>
182
+
<title>Examples of entering and exiting the PHP parser</title>
224
183
<programlisting role="php">
225
184
<![CDATA[
226
185
<?php
227
-
echo 'This is a test';
186
+
echo "This is a test\n";
228
187
?>
229
188
230
-
<?php echo 'This is a test' ?>
189
+
<?php echo "This is a test\n" ?>
231
190
232
-
<?php echo 'We omitted the last closing tag';
191
+
<?php echo "We omitted the last closing tag\n";
233
192
]]>
234
193
</programlisting>
235
-
</informalexample>
194
+
</example>
195
+
</para>
196
+
<para>
236
197
<note>
237
198
<para>
238
199
The closing tag of a PHP block at the end of a file is optional,
...
...
@@ -250,20 +211,22 @@ echo "Last statement";
250
211
<title>Comments</title>
251
212
<para>
252
213
PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:
253
-
254
-
<informalexample>
214
+
</para>
215
+
<para>
216
+
<example>
217
+
<title>Comments</title>
255
218
<programlisting role="php">
256
219
<![CDATA[
257
220
<?php
258
-
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
259
222
/* This is a multi line comment
260
223
yet another line of comment */
261
-
echo 'This is yet another test';
262
-
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
263
226
?>
264
227
]]>
265
228
</programlisting>
266
-
</informalexample>
229
+
</example>
267
230
</para>
268
231
<simpara>
269
232
The "one-line" comment styles only comment to the end of
...
...
@@ -272,25 +235,21 @@ echo "Last statement";
272
235
or <literal># ... ?></literal> WILL be printed:
273
236
?> breaks out of PHP mode and returns to HTML mode, and
274
237
<literal>//</literal> or <literal>#</literal> cannot influence that.
275
-
If the <link linkend="ini.asp-tags">asp_tags</link> configuration directive
276
-
is enabled, it behaves the same with <literal>// %></literal> and
277
-
<literal># %></literal>.
278
-
However, the <literal></script></literal> tag doesn't break out of PHP mode in
279
-
a one-line comment.
280
238
</simpara>
281
239
<para>
282
-
<informalexample>
240
+
<example>
241
+
<title>One Line Comments</title>
283
242
<programlisting role="php">
284
243
<![CDATA[
285
244
<h1>This is an <?php # echo 'simple';?> example</h1>
286
245
<p>The header above will say 'This is an example'.</p>
287
246
]]>
288
247
</programlisting>
289
-
</informalexample>
248
+
</example>
290
249
</para>
291
250
<simpara>
292
251
'C' style comments end at the first <literal>*/</literal> encountered.
293
-
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
294
253
mistake if you are trying to comment out a large block of code.
295
254
</simpara>
296
255
<para>
297
256