language/constants.xml
be039c085ee703d5b1f39837e55081d6e2d55030
...
...
@@ -6,11 +6,19 @@
6
6
<simpara>
7
7
A constant is an identifier (name) for a simple value. As the name
8
8
suggests, that value cannot change during the execution of the
9
-
script (except for <link linkend="language.constants.predefined">
9
+
script (except for <link linkend="language.constants.magic">
10
10
magic constants</link>, which aren't actually constants).
11
-
A constant is case-sensitive by default. By convention, constant
11
+
Constants are case-sensitive. By convention, constant
12
12
identifiers are always uppercase.
13
13
</simpara>
14
+

15
+
<note>
16
+
<para>
17
+
Prior to PHP 8.0.0, constants defined using the <function>define</function>
18
+
function may be case-insensitive.
19
+
</para>
20
+
</note>
21
+

14
22
<para>
15
23
The name of a constant follows the same rules as any label in PHP. A
16
24
valid constant name starts with a letter or underscore, followed
...
...
@@ -20,11 +28,12 @@
20
28
</para>
21
29
<para>
22
30
It is possible to <function>define</function> constants with reserved or even
23
-
invalid names, whose value can (only) be retrieved with
24
-
<function>constant</function>. However, doing so is not recommended.
31
+
invalid names, whose value can only be retrieved with the
32
+
<function>constant</function> function. However, doing so is not recommended.
25
33
</para>
26
34
&tip.userlandnaming;
27
35
<para>
36
+
<!-- TODO Move into syntax section? -->
28
37
<example>
29
38
<title>Valid and invalid constant names</title>
30
39
<programlisting role="php">
...
...
@@ -57,19 +66,26 @@ define("__FOO__", "something");
57
66
</note>
58
67

59
68
<simpara>
60
-
Like &link.superglobals;, the scope of a constant is global. You
61
-
can access constants anywhere in your script without regard to scope.
69
+
Like &link.superglobals;, the scope of a constant is global.
70
+
Constants can be accessed from anywhere in a script without regard to scope.
62
71
For more information on scope, read the manual section on
63
72
<link linkend="language.variables.scope">variable scope</link>.
64
73
</simpara>
65
74

75
+
<note>
76
+
<simpara>
77
+
As of PHP 7.1.0, class constant may declare a visibility of protected
78
+
or private, making them only available in the hierarchical scope of the
79
+
class in which it is defined.
80
+
</simpara>
81
+
</note>
82
+

66
83
<sect1 xml:id="language.constants.syntax">
67
84
<title>Syntax</title>
68
85
<simpara>
69
-
You can define a constant by using the
70
-
<function>define</function>-function or by using the
71
-
<literal>const</literal> keyword outside a class definition as
72
-
of PHP 5.3.0. While <function>define</function> allows a constant to be
86
+
Constants can be defined using the <literal>const</literal> keyword,
87
+
or by using the <function>define</function>-function.
88
+
While <function>define</function> allows a constant to be
73
89
defined to an arbitrary expression, the <literal>const</literal> keyword has
74
90
restrictions as outlined in the next paragraph.
75
91
Once a constant is defined, it can never be
...
...
@@ -77,24 +93,22 @@ define("__FOO__", "something");
77
93
</simpara>
78
94
<simpara>
79
95
When using the <literal>const</literal> keyword,
80
-
only scalar data (<type>boolean</type>, <type>integer</type>,
81
-
<type>float</type> and <type>string</type>) can be contained
82
-
in constants prior to PHP 5.6. From PHP 5.6 onwards, it is possible to
83
-
define a constant as a scalar expression, and it is also possible
84
-
to define an <type>array</type> constant. It is possible to define
85
-
constants as a <type>resource</type>, but it should be avoided, as it can
86
-
cause unexpected results.
96
+
only scalar (<type>bool</type>, <type>int</type>,
97
+
<type>float</type> and <type>string</type>) expressions and constant
98
+
<type>array</type>s containing only scalar expressions are accepted.
99
+
It is possible to define constants as a <type>resource</type>,
100
+
but it should be avoided, as it can cause unexpected results.
87
101
</simpara>
88
102
<simpara>
89
-
You can get the value of a constant by simply specifying its name.
90
-
Unlike with variables, you should <emphasis>not</emphasis> prepend
91
-
a constant with a <literal>$</literal>.
92
-
You can also use the function <function>constant</function> to
93
-
read a constant's value if you wish to obtain the constant's name
94
-
dynamically.
103
+
The value of a constant is accessed simply by specifying its name.
104
+
Unlike variables, a constant is <emphasis>not</emphasis> prepended
105
+
with a <literal>$</literal>.
106
+
It is also possible to use the <function>constant</function> function to
107
+
read a constant's value if the constant's name is obtained dynamically.
95
108
Use <function>get_defined_constants</function> to get a list of
96
109
all defined constants.
97
110
</simpara>
111
+

98
112
<note>
99
113
<simpara>
100
114
Constants and (global) variables are in a different namespace.
...
...
@@ -102,22 +116,29 @@ define("__FOO__", "something");
102
116
<varname>$TRUE</varname> are generally different.
103
117
</simpara>
104
118
</note>
119
+

105
120
<simpara>
106
-
If you use an undefined constant, PHP assumes that you mean
107
-
the name of the constant itself, just as if you called it as
108
-
a <type>string</type> (CONSTANT vs "CONSTANT").
121
+
If an undefined constant is used an <classname>Error</classname> is thrown.
122
+
Prior to PHP 8.0.0, undefined constants would be interpreted as a bare
123
+
word <type>string</type>, i.e. (CONSTANT vs "CONSTANT").
109
124
This fallback is deprecated as of PHP 7.2.0, and an error of level
110
-
<constant>E_WARNING</constant> is issued when it happens
111
-
(previously, an error of level
112
-
<link linkend="ref.errorfunc">E_NOTICE</link> has been issued instead.)
125
+
<constant>E_WARNING</constant> is issued when it happens.
126
+
Prior to PHP 7.2.0, an error of level
127
+
<link linkend="ref.errorfunc">E_NOTICE</link> has been issued instead.
113
128
See also the manual entry on why
114
129
<link linkend="language.types.array.foo-bar">$foo[bar]</link> is
115
-
wrong (unless you first <function>define</function>
116
-
<literal>bar</literal> as a constant). This does not apply to <link
130
+
wrong (unless <literal>bar</literal> is a constant).
131
+
This does not apply to <link
117
132
linkend="language.namespaces.rules">(fully) qualified constants</link>,
118
-
which will raise a fatal error if undefined. If you simply want to check if a
119
-
constant is set, use the <function>defined</function> function.
133
+
which will always raise a <classname>Error</classname> if undefined.
120
134
</simpara>
135
+

136
+
<note>
137
+
<simpara>
138
+
To check if a constant is set, use the <function>defined</function> function.
139
+
</simpara>
140
+
</note>
141
+

121
142
<para>
122
143
These are the differences between constants and variables:
123
144
<itemizedlist>
...
...
@@ -129,12 +150,6 @@ define("__FOO__", "something");
129
150
</listitem>
130
151
<listitem>
131
152
<simpara>
132
-
Prior to PHP 5.3, Constants may only be defined using the
133
-
<function>define</function> function, not by simple assignment;
134
-
</simpara>
135
-
</listitem>
136
-
<listitem>
137
-
<simpara>
138
153
Constants may be defined and accessed anywhere without regard
139
154
to variable scoping rules;
140
155
</simpara>
...
...
@@ -147,13 +162,8 @@ define("__FOO__", "something");
147
162
</listitem>
148
163
<listitem>
149
164
<simpara>
150
-
Constants may only evaluate to scalar values. As of PHP 5.6 it is possible
151
-
to define array constant using <literal>const</literal> keywords and as of
152
-
PHP 7 array constants can also be defined using <function>define</function>
153
-
You may use arrays in constant scalar expressions
154
-
(for example, <literal>const FOO = array(1,2,3)[0];</literal>),
155
-
but the end result must be a value of allowed type.
156
-
</simpara>
165
+
Constants may only evaluate to scalar values or arrays.
166
+
</simpara>
157
167
</listitem>
158
168
</itemizedlist>
159
169
</para>
...
...
@@ -166,7 +176,8 @@ define("__FOO__", "something");
166
176
<?php
167
177
define("CONSTANT", "Hello world.");
168
178
echo CONSTANT; // outputs "Hello world."
169
-
echo Constant; // outputs "Constant" and issues a notice.
179
+
echo Constant; // Emits an Error: Undefined constant "Constant"
180
+
// Prior to PHP 8.0.0, outputs "Constant" and issues a warning.
170
181
?>
171
182
]]>
172
183
</programlisting>
...
...
@@ -179,19 +190,19 @@ echo Constant; // outputs "Constant" and issues a notice.
179
190
<programlisting role="php">
180
191
<![CDATA[
181
192
<?php
182
-
// Works as of PHP 5.3.0
193
+
// Simple scalar value
183
194
const CONSTANT = 'Hello World';
184
195

185
196
echo CONSTANT;
186
197

187
-
// Works as of PHP 5.6.0
198
+
// Scalar expression
188
199
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
189
200
echo ANOTHER_CONST;
190
201

191
202
const ANIMALS = array('dog', 'cat', 'bird');
192
203
echo ANIMALS[1]; // outputs "cat"
193
204

194
-
// Works as of PHP 7
205
+
// Constant arrays
195
206
define('ANIMALS', array(
196
207
'dog',
197
208
'cat',
...
...
@@ -210,26 +221,23 @@ echo ANIMALS[1]; // outputs "cat"
210
221
constants defined using the <literal>const</literal> keyword must be
211
222
declared at the top-level scope because they are defined at compile-time.
212
223
This means that they cannot be declared inside functions, loops,
213
-
<literal>if</literal> statements or <literal>try</literal>/
214
-
<literal>catch</literal> blocks.
224
+
<literal>if</literal> statements or
225
+
<literal>try</literal>/<literal>catch</literal> blocks.
215
226
</para>
216
227
</note>
217
228

218
-
<note>
229
+
<sect2 role="seealso">
230
+
&reftitle.seealso;
219
231
<para>
220
-
Constants defined using the <literal>const</literal> keyword are always
221
-
case-sensitive, while constants defined using <function>define</function>
222
-
may be case-insensitive.
232
+
<simplelist>
233
+
<member><link linkend="language.oop5.constants">Class Constants</link></member>
234
+
</simplelist>
223
235
</para>
224
-
</note>
225
-

226
-
<simpara>
227
-
See also <link linkend="language.oop5.constants">Class Constants</link>.
228
-
</simpara>
236
+
</sect2>
229
237
</sect1>
230
238
231
239
<sect1 xml:id="language.constants.predefined">
232
-
<title>Magic constants</title>
240
+
<title>Predefined constants</title>
233
241

234
242
<simpara>
235
243
PHP provides a large number of <link
...
...
@@ -239,7 +247,10 @@ echo ANIMALS[1]; // outputs "cat"
239
247
are available, either via dynamic loading or because they have
240
248
been compiled in.
241
249
</simpara>
250
+
</sect1>
242
251

252
+
<sect1 xml:id="language.constants.magic">
253
+
<title>Magic constants</title>
243
254
<para>
244
255
There are nine magical constants that change depending on
245
256
where they are used. For example, the value of
...
...
@@ -250,12 +261,12 @@ echo ANIMALS[1]; // outputs "cat"
250
261
</para>
251
262
<para>
252
263
<table>
253
-
<title>A few "magical" PHP constants</title>
264
+
<title>PHP's magic constants</title>
254
265
<tgroup cols="2">
255
266
<thead>
256
267
<row>
257
-
<entry>Name</entry>
258
-
<entry>Description</entry>
268
+
<entry>&Name;</entry>
269
+
<entry>&Description;</entry>
259
270
</row>
260
271
</thead>
261
272
<tbody>
...
...
@@ -292,7 +303,7 @@ echo ANIMALS[1]; // outputs "cat"
292
303
<entry>
293
304
The class name. The class name includes the namespace
294
305
it was declared in (e.g. <literal>Foo\Bar</literal>).
295
-
Note that as of PHP 5.4 __CLASS__ works also in traits. When used
306
+
When used
296
307
in a trait method, __CLASS__ is the name of the class the trait
297
308
is used in.
298
309
</entry>
...
...
@@ -317,61 +328,29 @@ echo ANIMALS[1]; // outputs "cat"
317
328
</entry>
318
329
</row>
319
330
<row xml:id="constant.coloncolonclass">
320
-
<entry><constant>ClassName::class</constant></entry>
331
+
<entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
321
332
<entry>
322
-
The fully qualified class name. See also
323
-
<link linkend="language.oop5.basic.class.class">::class</link>.
333
+
The fully qualified class name.
324
334
</entry>
325
335
</row>
326
336
</tbody>
327
337
</tgroup>
328
338
</table>
329
339
</para>
330
-
<!-- <link linkend="language.oop5.basic.class.class">::class</link> -->
331
-
<para>
332
-
See also
333
-
<function>get_class</function>,
334
-
<function>get_object_vars</function>,
335
-
<function>file_exists</function>&listendand;
336
-
<function>function_exists</function>.
337
-
</para>
338
-
339
-
<sect2 xml:id="language.constants.predefined.changelog">
340
-
&reftitle.changelog;
341
340

341
+
<sect2 role="seealso">
342
+
&reftitle.seealso;
342
343
<para>
343
-
<informaltable>
344
-
<tgroup cols="2">
345
-
<thead>
346
-
<row>
347
-
<entry>&Version;</entry>
348
-
<entry>&Description;</entry>
349
-
</row>
350
-
</thead>
351
-
<tbody>
352
-
<row>
353
-
<entry>5.5.0</entry>
354
-
<entry>
355
-
Added <constant>::class</constant> magic constant
356
-
</entry>
357
-
</row>
358
-
<row>
359
-
<entry>5.4.0</entry>
360
-
<entry>
361
-
Added <constant>__TRAIT__</constant> constant
362
-
</entry>
363
-
</row>
364
-
<row>
365
-
<entry>5.3.0</entry>
366
-
<entry>
367
-
Added <constant>__DIR__</constant> and <constant>__NAMESPACE__</constant> constants
368
-
</entry>
369
-
</row>
370
-
</tbody>
371
-
</tgroup>
372
-
</informaltable>
344
+
<simplelist>
345
+
<member><link linkend="language.oop5.basic.class.class">::class</link></member>
346
+
<member><function>get_class</function></member>
347
+
<member><function>get_object_vars</function></member>
348
+
<member><function>file_exists</function></member>
349
+
<member><function>function_exists</function></member>
350
+
</simplelist>
373
351
</para>
374
352
</sect2>
353
+

375
354
</sect1>
376
355
</chapter>
377
356
378
357