language/constants.xml
be039c085ee703d5b1f39837e55081d6e2d55030
...
...
@@ -6,20 +6,34 @@
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
17
25
by any number of letters, numbers, or underscores. As a regular
18
26
expression, it would be expressed thusly:
19
-
<literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>
27
+
<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
28
+
</para>
29
+
<para>
30
+
It is possible to <function>define</function> constants with reserved or even
31
+
invalid names, whose value can only be retrieved with the
32
+
<function>constant</function> function. However, doing so is not recommended.
20
33
</para>
21
34
&tip.userlandnaming;
22
35
<para>
36
+
<!-- TODO Move into syntax section? -->
23
37
<example>
24
38
<title>Valid and invalid constant names</title>
25
39
<programlisting role="php">
...
...
@@ -47,45 +61,54 @@ define("__FOO__", "something");
47
61
<note>
48
62
<simpara>
49
63
For our purposes here, a letter is a-z, A-Z, and the ASCII
50
-
characters from 127 through 255 (0x7f-0xff).
64
+
characters from 128 through 255 (0x80-0xff).
51
65
</simpara>
52
66
</note>
53
67

54
68
<simpara>
55
-
Like &link.superglobals;, the scope of a constant is global. You
56
-
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.
57
71
For more information on scope, read the manual section on
58
72
<link linkend="language.variables.scope">variable scope</link>.
59
73
</simpara>
60
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
+

61
83
<sect1 xml:id="language.constants.syntax">
62
84
<title>Syntax</title>
63
85
<simpara>
64
-
You can define a constant by using the
65
-
<function>define</function>-function or by using the
66
-
<literal>const</literal> keyword outside a class definition as
67
-
of PHP 5.3.0. Once a constant is defined, it can never 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
89
+
defined to an arbitrary expression, the <literal>const</literal> keyword has
90
+
restrictions as outlined in the next paragraph.
91
+
Once a constant is defined, it can never be
68
92
changed or undefined.
69
93
</simpara>
70
94
<simpara>
71
-
Only scalar data (<type>boolean</type>, <type>integer</type>,
72
-
<type>float</type> and <type>string</type>) can be contained
73
-
in constants prior to PHP 5.6. From PHP 5.6 onwards, it is possible to
74
-
define a constant as a scalar expression, and it is also possible
75
-
to define an <type>array</type> constant. It is possible to define
76
-
constants as a <type>resource</type>, but it should be avoided, as it can
77
-
cause unexpected results.
95
+
When using the <literal>const</literal> keyword,
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.
78
101
</simpara>
79
102
<simpara>
80
-
You can get the value of a constant by simply specifying its name.
81
-
Unlike with variables, you should <emphasis>not</emphasis> prepend
82
-
a constant with a <literal>$</literal>.
83
-
You can also use the function <function>constant</function> to
84
-
read a constant's value if you wish to obtain the constant's name
85
-
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.
86
108
Use <function>get_defined_constants</function> to get a list of
87
109
all defined constants.
88
110
</simpara>
111
+

89
112
<note>
90
113
<simpara>
91
114
Constants and (global) variables are in a different namespace.
...
...
@@ -93,17 +116,29 @@ define("__FOO__", "something");
93
116
<varname>$TRUE</varname> are generally different.
94
117
</simpara>
95
118
</note>
119
+

96
120
<simpara>
97
-
If you use an undefined constant, PHP assumes that you mean
98
-
the name of the constant itself, just as if you called it as
99
-
a <type>string</type> (CONSTANT vs "CONSTANT"). An error of level
100
-
<link linkend="ref.errorfunc">E_NOTICE</link> will be issued
101
-
when this happens. See also the manual entry on why
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").
124
+
This fallback is deprecated as of PHP 7.2.0, and an error of level
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.
128
+
See also the manual entry on why
102
129
<link linkend="language.types.array.foo-bar">$foo[bar]</link> is
103
-
wrong (unless you first <function>define</function>
104
-
<literal>bar</literal> as a constant). If you simply want to check if a
105
-
constant is set, use the <function>defined</function> function.
130
+
wrong (unless <literal>bar</literal> is a constant).
131
+
This does not apply to <link
132
+
linkend="language.namespaces.rules">(fully) qualified constants</link>,
133
+
which will always raise a <classname>Error</classname> if undefined.
106
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
+

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

171
196
echo CONSTANT;
172
197

173
-
// Works as of PHP 5.6.0
198
+
// Scalar expression
174
199
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
175
200
echo ANOTHER_CONST;
176
201

177
202
const ANIMALS = array('dog', 'cat', 'bird');
178
203
echo ANIMALS[1]; // outputs "cat"
179
204

180
-
// Works as of PHP 7
205
+
// Constant arrays
181
206
define('ANIMALS', array(
182
207
'dog',
183
208
'cat',
...
...
@@ -196,18 +221,23 @@ echo ANIMALS[1]; // outputs "cat"
196
221
constants defined using the <literal>const</literal> keyword must be
197
222
declared at the top-level scope because they are defined at compile-time.
198
223
This means that they cannot be declared inside functions, loops,
199
-
<literal>if</literal> statements or <literal>try</literal>/
200
-
<literal>catch</literal> blocks.
224
+
<literal>if</literal> statements or
225
+
<literal>try</literal>/<literal>catch</literal> blocks.
201
226
</para>
202
227
</note>
203
228

204
-
<simpara>
205
-
See also <link linkend="language.oop5.constants">Class Constants</link>.
206
-
</simpara>
229
+
<sect2 role="seealso">
230
+
&reftitle.seealso;
231
+
<para>
232
+
<simplelist>
233
+
<member><link linkend="language.oop5.constants">Class Constants</link></member>
234
+
</simplelist>
235
+
</para>
236
+
</sect2>
207
237
</sect1>
208
238
209
239
<sect1 xml:id="language.constants.predefined">
210
-
<title>Magic constants</title>
240
+
<title>Predefined constants</title>
211
241

212
242
<simpara>
213
243
PHP provides a large number of <link
...
...
@@ -217,22 +247,26 @@ echo ANIMALS[1]; // outputs "cat"
217
247
are available, either via dynamic loading or because they have
218
248
been compiled in.
219
249
</simpara>
250
+
</sect1>
220
251

252
+
<sect1 xml:id="language.constants.magic">
253
+
<title>Magic constants</title>
221
254
<para>
222
-
There are eight magical constants that change depending on
255
+
There are nine magical constants that change depending on
223
256
where they are used. For example, the value of
224
257
<constant>__LINE__</constant> depends on the line that it's
225
-
used on in your script. These special constants are
226
-
case-insensitive and are as follows:
258
+
used on in your script. All these "magical" constants are resolved
259
+
at compile time, unlike regular constants, which are resolved at runtime.
260
+
These special constants are case-insensitive and are as follows:
227
261
</para>
228
262
<para>
229
263
<table>
230
-
<title>A few "magical" PHP constants</title>
264
+
<title>PHP's magic constants</title>
231
265
<tgroup cols="2">
232
266
<thead>
233
267
<row>
234
-
<entry>Name</entry>
235
-
<entry>Description</entry>
268
+
<entry>&Name;</entry>
269
+
<entry>&Description;</entry>
236
270
</row>
237
271
</thead>
238
272
<tbody>
...
...
@@ -261,7 +295,7 @@ echo ANIMALS[1]; // outputs "cat"
261
295
<row xml:id="constant.function">
262
296
<entry><constant>__FUNCTION__</constant></entry>
263
297
<entry>
264
-
The function name.
298
+
The function name, or <literal>{closure}</literal> for anonymous functions.
265
299
</entry>
266
300
</row>
267
301
<row xml:id="constant.class">
...
...
@@ -269,7 +303,7 @@ echo ANIMALS[1]; // outputs "cat"
269
303
<entry>
270
304
The class name. The class name includes the namespace
271
305
it was declared in (e.g. <literal>Foo\Bar</literal>).
272
-
Note that as of PHP 5.4 __CLASS__ works also in traits. When used
306
+
When used
273
307
in a trait method, __CLASS__ is the name of the class the trait
274
308
is used in.
275
309
</entry>
...
...
@@ -293,75 +327,30 @@ echo ANIMALS[1]; // outputs "cat"
293
327
The name of the current namespace.
294
328
</entry>
295
329
</row>
330
+
<row xml:id="constant.coloncolonclass">
331
+
<entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
332
+
<entry>
333
+
The fully qualified class name.
334
+
</entry>
335
+
</row>
296
336
</tbody>
297
337
</tgroup>
298
338
</table>
299
339
</para>
300
-
<para>
301
-
See also
302
-
<function>get_class</function>,
303
-
<function>get_object_vars</function>,
304
-
<function>file_exists</function>&listendand;
305
-
<function>function_exists</function>.
306
-
</para>
307
-
308
-
<sect2 xml:id="language.constants.predefined.changelog">
309
-
&reftitle.changelog;
310
340

341
+
<sect2 role="seealso">
342
+
&reftitle.seealso;
311
343
<para>
312
-
<informaltable>
313
-
<tgroup cols="2">
314
-
<thead>
315
-
<row>
316
-
<entry>&Version;</entry>
317
-
<entry>&Description;</entry>
318
-
</row>
319
-
</thead>
320
-
<tbody>
321
-
<row>
322
-
<entry>5.4.0</entry>
323
-
<entry>
324
-
Added <constant>__TRAIT__</constant> constant
325
-
</entry>
326
-
</row>
327
-
<row>
328
-
<entry>5.3.0</entry>
329
-
<entry>
330
-
Added <constant>__DIR__</constant> and <constant>__NAMESPACE__</constant> constants
331
-
</entry>
332
-
</row>
333
-
<row>
334
-
<entry>5.0.0</entry>
335
-
<entry>
336
-
Added <constant>__METHOD__</constant> constant
337
-
</entry>
338
-
</row>
339
-
<row>
340
-
<entry>5.0.0</entry>
341
-
<entry>
342
-
Before this version values of some magic constants were always lowercased.
343
-
All of them are case-sensitive now (contain names as they were declared).
344
-
</entry>
345
-
</row>
346
-
<row>
347
-
<entry>4.3.0</entry>
348
-
<entry>
349
-
Added <constant>__FUNCTION__</constant> and <constant>__CLASS__</constant> constants
350
-
</entry>
351
-
</row>
352
-
<row>
353
-
<entry>4.0.2</entry>
354
-
<entry>
355
-
<constant>__FILE__</constant> always contains an absolute path with symlinks
356
-
resolved whereas in older versions it contained relative path
357
-
under some circumstances
358
-
</entry>
359
-
</row>
360
-
</tbody>
361
-
</tgroup>
362
-
</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>
363
351
</para>
364
352
</sect2>
353
+

365
354
</sect1>
366
355
</chapter>
367
356
368
357