language/basic-syntax.xml
6b09bb638aa64d1fad5f4a630a8da9a2692ce733
6b09bb638aa64d1fad5f4a630a8da9a2692ce733
...
...
@@ -5,26 +5,59 @@
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 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.
14
+
</para>
15
+
16
+
<para>
17
+
PHP includes a short echo tag <literal><?=</literal> which is a
18
+
short-hand to the more verbose <code><?php echo</code>.
19
+
</para>
20
+
21
+
<para>
22
+
<example>
23
+
<title>PHP Opening and Closing Tags</title>
24
+
<programlisting role="php">
25
+
<![CDATA[
26
+
1. <?php echo 'if you want to serve PHP code in XHTML or XML documents,
27
+
use these tags'; ?>
28
+
29
+
2. You can use the short echo tag to <?= 'print this string' ?>.
30
+
It's equivalent to <?php echo 'print this string' ?>.
31
+
32
+
3. <? echo 'this code is within short tags, but will only work '.
33
+
'if short_open_tag is enabled'; ?>
34
+
]]>
35
+
</programlisting>
36
+
</example>
37
+
</para>
38
+
39
+
<para>
40
+
Short tags (example three) are available by default but can be disabled
41
+
either via the <link linkend="ini.short-open-tag">short_open_tag</link>
42
+
&php.ini; configuration file directive, or are disabled by default if
43
+
PHP is built with the <option>--disable-short-tags</option> configuration.
14
44
</para>
15
45
<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).
46
+
<note>
47
+
<para>
48
+
As short tags can be disabled it is recommended to only use the normal
49
+
tags (<code><?php ?></code> and <code><?= ?></code>) to
50
+
maximise compatibility.
51
+
</para>
52
+
</note>
21
53
</para>
54
+
22
55
<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.
56
+
If a file contains only PHP code, it is preferable to omit the PHP closing tag
57
+
at the end of the file. This prevents accidental whitespace or new lines
58
+
being added after the PHP closing tag, which may cause unwanted effects
59
+
because PHP will start output buffering when there is no intention from
60
+
the programmer to send any output at that point in the script.
28
61
<informalexample>
29
62
<programlisting role="php">
30
63
<![CDATA[
...
...
@@ -41,13 +74,14 @@ echo "Last statement";
41
74
</informalexample>
42
75
</para>
43
76
</sect1>
77
+
44
78
<sect1 xml:id="language.basic-syntax.phpmode">
45
79
<title>Escaping from HTML</title>
46
80
<para>
47
81
Everything outside of a pair of opening and closing tags is ignored by the
48
82
PHP parser which allows PHP files to have mixed content. This allows PHP
49
83
to be embedded in HTML documents, for example to create templates.
50
-
<example>
84
+
<informalexample>
51
85
<programlisting role="php">
52
86
<![CDATA[
53
87
<p>This is going to be ignored by PHP and displayed by the browser.</p>
...
...
@@ -55,9 +89,9 @@ echo "Last statement";
55
89
<p>This will also be ignored by PHP and displayed by the browser.</p>
56
90
]]>
57
91
</programlisting>
58
-
</example>
92
+
</informalexample>
59
93
This works as expected, because when the PHP interpreter hits the ?> closing
60
-
tags, it simply starts outputting whatever it finds (except for an
94
+
tags, it simply starts outputting whatever it finds (except for the
61
95
immediately following newline - see
62
96
<link linkend="language.basic-syntax.instruction-separation">instruction separation</link>)
63
97
until it hits another opening tag unless in the middle of a conditional
...
...
@@ -80,9 +114,9 @@ echo "Last statement";
80
114
</programlisting>
81
115
</example>
82
116
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
117
+
though they are outside of the PHP open/close tags; PHP skips them according
84
118
to the condition since the PHP interpreter will jump over blocks contained
85
-
within a condition what is not met.
119
+
within a condition that is not met.
86
120
</para>
87
121
<para>
88
122
For outputting large blocks of text, dropping out of PHP parsing mode is
...
...
@@ -90,86 +124,16 @@ echo "Last statement";
90
124
<function>echo</function> or <function>print</function>.
91
125
</para>
92
126
<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
127
<note>
158
128
<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
-
<note>
166
-
<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.
129
+
If PHP is embeded within XML or XHTML the normal PHP
130
+
<code><?php ?></code> must be used to remain compliant
131
+
with the standards.
169
132
</para>
170
133
</note>
171
134
</para>
172
135
</sect1>
136
+
173
137
<sect1 xml:id="language.basic-syntax.instruction-separation">
174
138
<title>Instruction separation</title>
175
139
<para>
...
...
@@ -179,6 +143,31 @@ echo "Last statement";
179
143
do not need to have a semicolon terminating the last line of a
180
144
PHP block. The closing tag for the block will include the immediately
181
145
trailing newline if one is present.
146
+
</para>
147
+
148
+
<para>
149
+
<example>
150
+
<title>Example showing the closing tag encompassing the trailing newline</title>
151
+
<programlisting role="php">
152
+
<![CDATA[
153
+
<?php echo "Some text"; ?>
154
+
No newline
155
+
<?= "But newline now" ?>
156
+
]]>
157
+
</programlisting>
158
+
&example.outputs;
159
+
<screen>
160
+
<![CDATA[
161
+
Some textNo newline
162
+
But newline now
163
+
]]>
164
+
</screen>
165
+
</example>
166
+
</para>
167
+
168
+
<para>
169
+
Examples of entering and exiting the PHP parser:
170
+
182
171
<informalexample>
183
172
<programlisting role="php">
184
173
<![CDATA[
...
...
@@ -231,11 +220,6 @@ echo "Last statement";
231
220
or <literal># ... ?></literal> WILL be printed:
232
221
?> breaks out of PHP mode and returns to HTML mode, and
233
222
<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
223
</simpara>
240
224
<para>
241
225
<informalexample>
242
226