reference/misc/functions/define.xml
cdc9d28d334bbc08386fecf8aade66080004a9dd
cdc9d28d334bbc08386fecf8aade66080004a9dd
...
...
@@ -10,9 +10,9 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>define</methodname>
13
-
<methodparam><type>string</type><parameter>name</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>constant_name</parameter></methodparam>
14
14
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
15
-
<methodparam choice="opt"><type>bool</type><parameter>case_insensitive</parameter><initializer>false</initializer></methodparam>
15
+
<methodparam choice="opt"><type>bool</type><parameter>case_insensitive</parameter><initializer>&false;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
Defines a named constant at runtime.
...
...
@@ -24,23 +24,35 @@
24
24
<para>
25
25
<variablelist>
26
26
<varlistentry>
27
-
<term><parameter>name</parameter></term>
27
+
<term><parameter>constant_name</parameter></term>
28
28
<listitem>
29
29
<para>
30
30
The name of the constant.
31
31
</para>
32
+
<note>
33
+
<para>
34
+
It is possible to <function>define</function> constants with reserved or
35
+
even invalid names, whose value can (only) be retrieved with
36
+
<function>constant</function>. However, doing so is not recommended.
37
+
</para>
38
+
</note>
32
39
</listitem>
33
40
</varlistentry>
34
41
<varlistentry>
35
42
<term><parameter>value</parameter></term>
36
43
<listitem>
37
44
<para>
38
-
The value of the constant; only scalar and <type>null</type> values are allowed.
39
-
Scalar values are <type>integer</type>,
40
-
<type>float</type>, <type>string</type> or <type>boolean</type> values. It is
41
-
possible to define <type>resource</type> constants, however it is not recommended
42
-
and may cause unpredictable behavior.
45
+
The value of the constant. In PHP 5, <parameter>value</parameter> must
46
+
be a <type>scalar</type> value (<type>int</type>,
47
+
<type>float</type>, <type>string</type>, <type>bool</type>, or
48
+
&null;). In PHP 7, <type>array</type> values are also accepted.
43
49
</para>
50
+
<warning>
51
+
<para>
52
+
While it is possible to define <type>resource</type> constants, it is
53
+
not recommended and may cause unpredictable behavior.
54
+
</para>
55
+
</warning>
44
56
</listitem>
45
57
</varlistentry>
46
58
<varlistentry>
...
...
@@ -52,6 +64,13 @@
52
64
<literal>CONSTANT</literal> and <literal>Constant</literal> represent
53
65
different values.
54
66
</para>
67
+
<warning>
68
+
<simpara>
69
+
Defining case-insensitive constants is deprecated as of PHP 7.3.0.
70
+
As of PHP 8.0.0, only &false; is an acceptable value, passing
71
+
&true; will produce a warning.
72
+
</simpara>
73
+
</warning>
55
74
<note>
56
75
<para>
57
76
Case-insensitive constants are stored as lower-case.
...
...
@@ -70,6 +89,42 @@
70
89
</para>
71
90
</refsect1>
72
91
92
+
<refsect1 role="changelog">
93
+
&reftitle.changelog;
94
+
<para>
95
+
<informaltable>
96
+
<tgroup cols="2">
97
+
<thead>
98
+
<row>
99
+
<entry>&Version;</entry>
100
+
<entry>&Description;</entry>
101
+
</row>
102
+
</thead>
103
+
<tbody>
104
+
<row>
105
+
<entry>8.0.0</entry>
106
+
<entry>
107
+
Passing &true; to <parameter>case_insensitive</parameter> now emits an <constant>E_WARNING</constant>. Passing &false; is still allowed.
108
+
</entry>
109
+
</row>
110
+
<row>
111
+
<entry>7.3.0</entry>
112
+
<entry>
113
+
<parameter>case_insensitive</parameter> has been deprecated and will be removed in version 8.0.0.
114
+
</entry>
115
+
</row>
116
+
<row>
117
+
<entry>7.0.0</entry>
118
+
<entry>
119
+
<type>array</type> values are allowed.
120
+
</entry>
121
+
</row>
122
+
</tbody>
123
+
</tgroup>
124
+
</informaltable>
125
+
</para>
126
+
</refsect1>
127
+
73
128
<refsect1 role="examples">
74
129
&reftitle.examples;
75
130
<para>
...
...
@@ -86,9 +141,48 @@ define("GREETING", "Hello you.", true);
86
141
echo GREETING; // outputs "Hello you."
87
142
echo Greeting; // outputs "Hello you."
88
143
144
+
// Works as of PHP 7
145
+
define('ANIMALS', array(
146
+
'dog',
147
+
'cat',
148
+
'bird'
149
+
));
150
+
echo ANIMALS[1]; // outputs "cat"
151
+
152
+
?>
153
+
]]>
154
+
</programlisting>
155
+
</example>
156
+
</para>
157
+
<para>
158
+
<example>
159
+
<title>Constants with Reserved Names</title>
160
+
<para>
161
+
This example illustrates the <emphasis>possibility</emphasis> to define a
162
+
constant with the same name as a
163
+
<link linkend="language.constants.predefined">magic constant</link>.
164
+
Since the resulting behavior is obviously confusing, it is not recommended
165
+
to do this in practise, though.
166
+
</para>
167
+
<programlisting role="php">
168
+
<![CDATA[
169
+
<?php
170
+
var_dump(defined('__LINE__'));
171
+
var_dump(define('__LINE__', 'test'));
172
+
var_dump(constant('__LINE__'));
173
+
var_dump(__LINE__);
89
174
?>
90
175
]]>
91
176
</programlisting>
177
+
&example.outputs;
178
+
<screen>
179
+
<![CDATA[
180
+
bool(false)
181
+
bool(true)
182
+
string(4) "test"
183
+
int(5)
184
+
]]>
185
+
</screen>
92
186
</example>
93
187
</para>
94
188
</refsect1>
...
...
@@ -105,7 +199,6 @@ echo Greeting; // outputs "Hello you."
105
199
</refsect1>
106
200
107
201
</refentry>
108
-
109
202
<!-- Keep this comment at the end of the file
110
203
Local variables:
111
204
mode: sgml
112
205