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,24 +61,31 @@ 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. 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
68
89
defined to an arbitrary expression, the <literal>const</literal> keyword has
69
90
restrictions as outlined in the next paragraph.
70
91
Once a constant is defined, it can never be
...
...
@@ -72,24 +93,22 @@ define("__FOO__", "something");
72
93
</simpara>
73
94
<simpara>
74
95
When using the <literal>const</literal> keyword,
75
-
only scalar data (<type>boolean</type>, <type>integer</type>,
76
-
<type>float</type> and <type>string</type>) can be contained
77
-
in constants prior to PHP 5.6. From PHP 5.6 onwards, it is possible to
78
-
define a constant as a scalar expression, and it is also possible
79
-
to define an <type>array</type> constant. It is possible to define
80
-
constants as a <type>resource</type>, but it should be avoided, as it can
81
-
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.
82
101
</simpara>
83
102
<simpara>
84
-
You can get the value of a constant by simply specifying its name.
85
-
Unlike with variables, you should <emphasis>not</emphasis> prepend
86
-
a constant with a <literal>$</literal>.
87
-
You can also use the function <function>constant</function> to
88
-
read a constant's value if you wish to obtain the constant's name
89
-
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.
90
108
Use <function>get_defined_constants</function> to get a list of
91
109
all defined constants.
92
110
</simpara>
111
+

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

100
120
<simpara>
101
-
If you use an undefined constant, PHP assumes that you mean
102
-
the name of the constant itself, just as if you called it as
103
-
a <type>string</type> (CONSTANT vs "CONSTANT"). An error of level
104
-
<link linkend="ref.errorfunc">E_NOTICE</link> will be issued
105
-
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
106
129
<link linkend="language.types.array.foo-bar">$foo[bar]</link> is
107
-
wrong (unless you first <function>define</function>
108
-
<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
109
132
linkend="language.namespaces.rules">(fully) qualified constants</link>,
110
-
which will raise a fatal error if undefined. If you simply want to check if a
111
-
constant is set, use the <function>defined</function> function.
133
+
which will always raise a <classname>Error</classname> if undefined.
112
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
+

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

177
196
echo CONSTANT;
178
197

179
-
// Works as of PHP 5.6.0
198
+
// Scalar expression
180
199
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
181
200
echo ANOTHER_CONST;
182
201

183
202
const ANIMALS = array('dog', 'cat', 'bird');
184
203
echo ANIMALS[1]; // outputs "cat"
185
204

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

210
-
<simpara>
211
-
See also <link linkend="language.oop5.constants">Class Constants</link>.
212
-
</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>
213
237
</sect1>
214
238
215
239
<sect1 xml:id="language.constants.predefined">
216
-
<title>Magic constants</title>
240
+
<title>Predefined constants</title>
217
241

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

252
+
<sect1 xml:id="language.constants.magic">
253
+
<title>Magic constants</title>
227
254
<para>
228
255
There are nine magical constants that change depending on
229
256
where they are used. For example, the value of
230
257
<constant>__LINE__</constant> depends on the line that it's
231
258
used on in your script. All these "magical" constants are resolved
232
-
at compile time, unlike regular constants thats resolved at runtime.
259
+
at compile time, unlike regular constants, which are resolved at runtime.
233
260
These special constants are case-insensitive and are as follows:
234
261
</para>
235
262
<para>
236
263
<table>
237
-
<title>A few "magical" PHP constants</title>
264
+
<title>PHP's magic constants</title>
238
265
<tgroup cols="2">
239
266
<thead>
240
267
<row>
241
-
<entry>Name</entry>
242
-
<entry>Description</entry>
268
+
<entry>&Name;</entry>
269
+
<entry>&Description;</entry>
243
270
</row>
244
271
</thead>
245
272
<tbody>
...
...
@@ -268,7 +295,7 @@ echo ANIMALS[1]; // outputs "cat"
268
295
<row xml:id="constant.function">
269
296
<entry><constant>__FUNCTION__</constant></entry>
270
297
<entry>
271
-
The function name.
298
+
The function name, or <literal>{closure}</literal> for anonymous functions.
272
299
</entry>
273
300
</row>
274
301
<row xml:id="constant.class">
...
...
@@ -276,7 +303,7 @@ echo ANIMALS[1]; // outputs "cat"
276
303
<entry>
277
304
The class name. The class name includes the namespace
278
305
it was declared in (e.g. <literal>Foo\Bar</literal>).
279
-
Note that as of PHP 5.4 __CLASS__ works also in traits. When used
306
+
When used
280
307
in a trait method, __CLASS__ is the name of the class the trait
281
308
is used in.
282
309
</entry>
...
...
@@ -301,88 +328,29 @@ echo ANIMALS[1]; // outputs "cat"
301
328
</entry>
302
329
</row>
303
330
<row xml:id="constant.coloncolonclass">
304
-
<entry><constant>ClassName::class</constant></entry>
331
+
<entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
305
332
<entry>
306
-
The fully qualified class name. See also
307
-
<link linkend="language.oop5.basic.class.class">::class</link>.
333
+
The fully qualified class name.
308
334
</entry>
309
335
</row>
310
336
</tbody>
311
337
</tgroup>
312
338
</table>
313
339
</para>
314
-
<!-- <link linkend="language.oop5.basic.class.class">::class</link> -->
315
-
<para>
316
-
See also
317
-
<function>get_class</function>,
318
-
<function>get_object_vars</function>,
319
-
<function>file_exists</function>&listendand;
320
-
<function>function_exists</function>.
321
-
</para>
322
-
323
-
<sect2 xml:id="language.constants.predefined.changelog">
324
-
&reftitle.changelog;
325
340

341
+
<sect2 role="seealso">
342
+
&reftitle.seealso;
326
343
<para>
327
-
<informaltable>
328
-
<tgroup cols="2">
329
-
<thead>
330
-
<row>
331
-
<entry>&Version;</entry>
332
-
<entry>&Description;</entry>
333
-
</row>
334
-
</thead>
335
-
<tbody>
336
-
<row>
337
-
<entry>5.5.0</entry>
338
-
<entry>
339
-
Added <constant>::class</constant> magic constant
340
-
</entry>
341
-
</row>
342
-
<row>
343
-
<entry>5.4.0</entry>
344
-
<entry>
345
-
Added <constant>__TRAIT__</constant> constant
346
-
</entry>
347
-
</row>
348
-
<row>
349
-
<entry>5.3.0</entry>
350
-
<entry>
351
-
Added <constant>__DIR__</constant> and <constant>__NAMESPACE__</constant> constants
352
-
</entry>
353
-
</row>
354
-
<row>
355
-
<entry>5.0.0</entry>
356
-
<entry>
357
-
Added <constant>__METHOD__</constant> constant
358
-
</entry>
359
-
</row>
360
-
<row>
361
-
<entry>5.0.0</entry>
362
-
<entry>
363
-
Before this version values of some magic constants were always lowercased.
364
-
All of them are case-sensitive now (contain names as they were declared).
365
-
</entry>
366
-
</row>
367
-
<row>
368
-
<entry>4.3.0</entry>
369
-
<entry>
370
-
Added <constant>__FUNCTION__</constant> and <constant>__CLASS__</constant> constants
371
-
</entry>
372
-
</row>
373
-
<row>
374
-
<entry>4.0.2</entry>
375
-
<entry>
376
-
<constant>__FILE__</constant> always contains an absolute path with symlinks
377
-
resolved whereas in older versions it contained relative path
378
-
under some circumstances
379
-
</entry>
380
-
</row>
381
-
</tbody>
382
-
</tgroup>
383
-
</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>
384
351
</para>
385
352
</sect2>
353
+

386
354
</sect1>
387
355
</chapter>
388
356
389
357



Tools (Spanish Manual)