language/variables.xml
5700871f9d037a59d137be318f89deb7e146bbf6
5700871f9d037a59d137be318f89deb7e146bbf6
...
...
@@ -16,13 +16,13 @@
16
16
valid variable name starts with a letter or underscore, followed
17
17
by any number of letters, numbers, or underscores. As a regular
18
18
expression, it would be expressed thus:
19
-
'<literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>'
19
+
<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
20
20
</para>
21
21
22
22
<note>
23
23
<simpara>
24
24
For our purposes here, a letter is a-z, A-Z, and the bytes
25
-
from 127 through 255 (<literal>0x7f-0xff</literal>).
25
+
from 128 through 255 (<literal>0x80-0xff</literal>).
26
26
</simpara>
27
27
</note>
28
28
...
...
@@ -30,6 +30,9 @@
30
30
<simpara>
31
31
<literal>$this</literal> is a special variable that can't be
32
32
assigned.
33
+
Prior to PHP 7.1.0, indirect assignment (e.g. by using
34
+
<link linkend="language.variables.variable">variable variables</link>)
35
+
was possible.
33
36
</simpara>
34
37
</note>
35
38
...
...
@@ -135,7 +138,7 @@ $bar = &test(); // Invalid.
135
138
var_dump($unset_var);
136
139
137
140
// Boolean usage; outputs 'false' (See ternary operators for more on this syntax)
138
-
echo($unset_bool ? "true\n" : "false\n");
141
+
echo $unset_bool ? "true\n" : "false\n";
139
142
140
143
// String usage; outputs 'string(3) "abc"'
141
144
$unset_str .= 'abc';
...
...
@@ -145,7 +148,7 @@ var_dump($unset_str);
145
148
$unset_int += 25; // 0 + 25 => 25
146
149
var_dump($unset_int);
147
150
148
-
// Float/double usage; outputs 'float(1.25)'
151
+
// Float usage; outputs 'float(1.25)'
149
152
$unset_float += 1.25;
150
153
var_dump($unset_float);
151
154
...
...
@@ -165,10 +168,9 @@ var_dump($unset_obj);
165
168
<para>
166
169
Relying on the default value of an uninitialized variable is problematic
167
170
in the case of including one file into another which uses the same
168
-
variable name. It is also a major <link
169
-
linkend="security.globals">security risk</link> with <link
170
-
linkend="ini.register-globals">register_globals</link> turned on. <link
171
-
linkend="errorfunc.constants.errorlevels.e-notice">E_NOTICE</link> level error is issued in case of
171
+
variable name.
172
+
<constant>E_WARNING</constant> (prior to PHP 8.0.0, <constant>E_NOTICE</constant>)
173
+
level error is issued in case of
172
174
working with uninitialized variables, however not in the case of appending
173
175
elements to the uninitialized array. <function>isset</function> language
174
176
construct can be used to detect if a variable has been already initialized.
...
...
@@ -178,62 +180,28 @@ var_dump($unset_obj);
178
180
<sect1 xml:id="language.variables.predefined">
179
181
<title>Predefined Variables</title>
180
182
181
-
<simpara>
183
+
<para>
182
184
PHP provides a large number of predefined variables to any script
183
185
which it runs. Many of these variables, however, cannot be fully
184
186
documented as they are dependent upon which server is running, the
185
187
version and setup of the server, and other factors. Some of these
186
188
variables will not be available when PHP is run on the
187
189
<link linkend="features.commandline">command line</link>.
188
-
For a listing of these variables, please see the section on
189
-
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
190
-
</simpara>
191
-
192
-
<warning>
193
-
<simpara>
194
-
In PHP 4.2.0 and later, the default value for the PHP directive <link
195
-
linkend="ini.register-globals">register_globals</link> is
196
-
<emphasis>off</emphasis>. This is a major change in PHP. Having
197
-
register_globals <emphasis>off</emphasis> affects the set of predefined
198
-
variables available in the global scope. For example, to get
199
-
<varname>DOCUMENT_ROOT</varname> you'll use
200
-
<varname>$_SERVER['DOCUMENT_ROOT']</varname> instead of
201
-
<varname>$DOCUMENT_ROOT</varname>, or <varname>$_GET['id']</varname> from
202
-
the URL <literal>http://www.example.com/test.php?id=3</literal> instead
203
-
of <varname>$id</varname>, or <varname>$_ENV['HOME']</varname> instead of
204
-
<varname>$HOME</varname>.
205
-
</simpara>
206
-
<simpara>
207
-
For related information on this change, read the configuration entry for
208
-
<link linkend="ini.register-globals">register_globals</link>, the security
209
-
chapter on <link linkend="security.globals">Using Register Globals
210
-
</link>, as well as the PHP <link xlink:href="&url.php.release4.1.0;">4.1.0
211
-
</link> and <link xlink:href="&url.php.release4.2.0;">4.2.0</link> Release
212
-
Announcements.
213
-
</simpara>
214
-
<simpara>
215
-
Using the available PHP Reserved Predefined Variables, like the
216
-
<link linkend="language.variables.superglobals">superglobal arrays</link>,
217
-
is preferred.
218
-
</simpara>
219
-
</warning>
190
+
Refer to the <link linkend="reserved.variables">list of predefined variables</link>
191
+
for details.
192
+
</para>
220
193
221
-
<simpara>
222
-
From version 4.1.0 onward, PHP provides an additional set of predefined arrays
194
+
<para>
195
+
PHP also provides an additional set of predefined arrays
223
196
containing variables from the web server (if applicable), the
224
-
environment, and user input. These new arrays are rather special
225
-
in that they are automatically global--i.e., automatically
197
+
environment, and user input. These arrays are rather special
198
+
in that they are automatically global - i.e., automatically
226
199
available in every scope. For this reason, they are often known as
227
200
"superglobals". (There is no mechanism in PHP for
228
-
user-defined superglobals.) The superglobals are listed below;
229
-
however, for a listing of their contents and further discussion on
230
-
PHP predefined variables and their natures, please see the section
231
-
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
232
-
Also, you'll notice how the older predefined variables
233
-
(<varname>$HTTP_*_VARS</varname>) still exist.
234
-
235
-
&avail.register-long-arrays;
236
-
</simpara>
201
+
user-defined superglobals.) Refer to the
202
+
<link linkend="language.variables.superglobals">list of superglobals</link>
203
+
for details.
204
+
</para>
237
205
238
206
<note>
239
207
<title>Variable variables</title>
...
...
@@ -244,13 +212,6 @@ var_dump($unset_obj);
244
212
</para>
245
213
</note>
246
214
247
-
<note>
248
-
<para>
249
-
Even though both the superglobal and <literal>HTTP_*_VARS</literal> can exist at the same
250
-
time; they are not identical, so modifying one will not change the other.
251
-
</para>
252
-
</note>
253
-
254
215
<para>
255
216
If certain variables in <link
256
217
linkend="ini.variables-order">variables_order</link> are not set, their
...
...
@@ -265,8 +226,8 @@ var_dump($unset_obj);
265
226
<simpara>
266
227
The scope of a variable is the context within which it is defined.
267
228
For the most part all PHP variables only have a single scope.
268
-
This single scope spans included and required files as well. For
269
-
example:
229
+
This single scope spans <function>include</function>d and
230
+
<function>require</function>d files as well. For example:
270
231
</simpara>
271
232
<informalexample>
272
233
<programlisting role="php">
...
...
@@ -304,7 +265,12 @@ test();
304
265
</informalexample>
305
266
306
267
<simpara>
307
-
This script will not produce any output because the echo statement
268
+
This script will generate an undefined variable <constant>E_WARNING</constant>
269
+
(or a <constant>E_NOTICE</constant> prior to PHP 8.0.0)
270
+
diagnostic. However, if the
271
+
<link linkend="ini.display-errors">display_errors</link> INI setting is set to hide
272
+
such diagnostics then nothing at all will be outputted.
273
+
This is because the echo statement
308
274
refers to a local version of the <varname>$a</varname> variable,
309
275
and it has not been assigned a value within this scope. You may
310
276
notice that this is a little bit different from the C language in
...
...
@@ -395,18 +361,8 @@ echo $b;
395
361
<programlisting role="php">
396
362
<![CDATA[
397
363
<?php
398
-
function test_global()
364
+
function test_superglobal()
399
365
{
400
-
// Most predefined variables aren't "super" and require
401
-
// 'global' to be available to the functions local scope.
402
-
global $HTTP_POST_VARS;
403
-
404
-
echo $HTTP_POST_VARS['name'];
405
-
406
-
// Superglobals are available in any scope and do
407
-
// not require 'global'. Superglobals are available
408
-
// as of PHP 4.1.0, and HTTP_POST_VARS is now
409
-
// deemed deprecated.
410
366
echo $_POST['name'];
411
367
}
412
368
?>
...
...
@@ -512,32 +468,59 @@ function test()
512
468
</example>
513
469
</para>
514
470
515
-
<note>
516
-
<para>
517
-
Static variables may be declared as seen in the examples above.
518
-
Trying to assign values to these variables which are the
519
-
result of expressions will cause a parse error.
520
-
</para>
521
-
<para>
522
-
<example>
523
-
<title>Declaring static variables</title>
524
-
<programlisting role="php">
471
+
<para>
472
+
Static variables can be assigned values which are the
473
+
result of constant expressions, but dynamic expressions, such as function
474
+
calls, will cause a parse error.
475
+
</para>
476
+
<para>
477
+
<example>
478
+
<title>Declaring static variables</title>
479
+
<programlisting role="php">
525
480
<![CDATA[
526
481
<?php
527
482
function foo(){
528
483
static $int = 0; // correct
529
-
static $int = 1+2; // wrong (as it is an expression)
530
-
static $int = sqrt(121); // wrong (as it is an expression too)
484
+
static $int = 1+2; // correct
485
+
static $int = sqrt(121); // wrong (as it is a function)
531
486
532
487
$int++;
533
488
echo $int;
534
489
}
535
490
?>
536
491
]]>
537
-
</programlisting>
538
-
</example>
539
-
</para>
540
-
</note>
492
+
</programlisting>
493
+
</example>
494
+
</para>
495
+
496
+
<para>
497
+
As of PHP 8.1.0, when a method using static variables is inherited (but not overridden),
498
+
the inherited method will now share static variables with the parent method.
499
+
This means that static variables in methods now behave the same way as static properties.
500
+
</para>
501
+
502
+
<example>
503
+
<title>Usage of static Variables in Inherited Methods</title>
504
+
<programlisting role="php">
505
+
<![CDATA[
506
+
<?php
507
+
class Foo {
508
+
public static function counter() {
509
+
static $counter = 0;
510
+
$counter++;
511
+
return $counter;
512
+
}
513
+
}
514
+
class Bar extends Foo {}
515
+
var_dump(Foo::counter()); // int(1)
516
+
var_dump(Foo::counter()); // int(2)
517
+
var_dump(Bar::counter()); // int(3), prior to PHP 8.1.0 int(1)
518
+
var_dump(Bar::counter()); // int(4), prior to PHP 8.1.0 int(2)
519
+
?>
520
+
]]>
521
+
</programlisting>
522
+
</example>
523
+
541
524
<note>
542
525
<para>
543
526
Static declarations are resolved in compile-time.
...
...
@@ -548,7 +531,7 @@ function foo(){
548
531
<sect2 xml:id="language.variables.scope.references">
549
532
<title>References with <literal>global</literal> and <literal>static</literal> variables</title>
550
533
<simpara>
551
-
The Zend Engine 1, driving PHP 4, implements the
534
+
PHP implements the
552
535
<link linkend="language.variables.scope.static">static</link> and
553
536
<link linkend="language.variables.scope.global">global</link> modifier
554
537
for variables in terms of <link linkend="language.references">
...
...
@@ -564,12 +547,14 @@ function foo(){
564
547
<?php
565
548
function test_global_ref() {
566
549
global $obj;
567
-
$obj = &new stdclass;
550
+
$new = new stdClass;
551
+
$obj = &$new;
568
552
}
569
553
570
554
function test_global_noref() {
571
555
global $obj;
572
-
$obj = new stdclass;
556
+
$new = new stdClass;
557
+
$obj = $new;
573
558
}
574
559
575
560
test_global_ref();
...
...
@@ -584,9 +569,11 @@ var_dump($obj);
584
569
&example.outputs;
585
570
586
571
<screen>
572
+
<![CDATA[
587
573
NULL
588
-
object(stdClass)(0) {
574
+
object(stdClass)#1 (0) {
589
575
}
576
+
]]>
590
577
</screen>
591
578
592
579
<simpara>
...
...
@@ -604,10 +591,15 @@ function &get_instance_ref() {
604
591
echo 'Static object: ';
605
592
var_dump($obj);
606
593
if (!isset($obj)) {
594
+
$new = new stdClass;
607
595
// Assign a reference to the static variable
608
-
$obj = &new stdclass;
596
+
$obj = &$new;
597
+
}
598
+
if (!isset($obj->property)) {
599
+
$obj->property = 1;
600
+
} else {
601
+
$obj->property++;
609
602
}
610
-
$obj->property++;
611
603
return $obj;
612
604
}
613
605
...
...
@@ -617,10 +609,15 @@ function &get_instance_noref() {
617
609
echo 'Static object: ';
618
610
var_dump($obj);
619
611
if (!isset($obj)) {
612
+
$new = new stdClass;
620
613
// Assign the object to the static variable
621
-
$obj = new stdclass;
614
+
$obj = $new;
615
+
}
616
+
if (!isset($obj->property)) {
617
+
$obj->property = 1;
618
+
} else {
619
+
$obj->property++;
622
620
}
623
-
$obj->property++;
624
621
return $obj;
625
622
}
626
623
...
...
@@ -635,14 +632,16 @@ $still_obj2 = get_instance_noref();
635
632
</informalexample>
636
633
&example.outputs;
637
634
<screen>
635
+
<![CDATA[
638
636
Static object: NULL
639
637
Static object: NULL
640
638
641
639
Static object: NULL
642
-
Static object: object(stdClass)(1) {
640
+
Static object: object(stdClass)#3 (1) {
643
641
["property"]=>
644
642
int(1)
645
643
}
644
+
]]>
646
645
</screen>
647
646
648
647
<simpara>
...
...
@@ -700,7 +699,7 @@ $$a = 'world';
700
699
<programlisting role="php">
701
700
<![CDATA[
702
701
<?php
703
-
echo "$a ${$a}";
702
+
echo "$a {$$a}";
704
703
?>
705
704
]]>
706
705
</programlisting>
...
...
@@ -736,19 +735,19 @@ echo "$a $hello";
736
735
</simpara>
737
736
738
737
<simpara>
739
-
Class properties may also be accessed using variable property
740
-
names. The variable property name will be resolved within the
741
-
scope from which the call is made. For instance, if you have an
742
-
expression such as <varname>$foo->$bar</varname>, then the local
743
-
scope will be examined for <varname>$bar</varname> and its value
744
-
will be used as the name of the property
745
-
of <varname>$foo</varname>. This is also true
746
-
if <varname>$bar</varname> is an array access.
738
+
Class properties may also be accessed using variable property names. The
739
+
variable property name will be resolved within the scope from which the
740
+
call is made. For instance, if you have an expression such as
741
+
<varname>$foo->$bar</varname>, then the local scope will be examined for
742
+
<varname>$bar</varname> and its value will be used as the name of the
743
+
property of <varname>$foo</varname>. This is also true if
744
+
<varname>$bar</varname> is an array access.
747
745
</simpara>
746
+
748
747
<simpara>
749
748
Curly braces may also be used, to clearly delimit the property
750
749
name. They are most useful when accessing values within a property that
751
-
contains an array, when the property name is made of mulitple parts,
750
+
contains an array, when the property name is made of multiple parts,
752
751
or when the property name contains characters that are not
753
752
otherwise valid (e.g. from <function>json_decode</function>
754
753
or <link linkend="book.simplexml">SimpleXML</link>).
...
...
@@ -770,15 +769,14 @@ $foo = new foo();
770
769
$bar = 'bar';
771
770
$baz = array('foo', 'bar', 'baz', 'quux');
772
771
echo $foo->$bar . "\n";
773
-
echo $foo->$baz[1] . "\n";
772
+
echo $foo->{$baz[1]} . "\n";
774
773
775
774
$start = 'b';
776
775
$end = 'ar';
777
776
echo $foo->{$start . $end} . "\n";
778
777
779
778
$arr = 'arr';
780
-
echo $foo->$arr[1] . "\n";
781
-
echo $foo->{$arr}[1] . "\n";
779
+
echo $foo->{$arr[1]} . "\n";
782
780
783
781
?>
784
782
]]>
...
...
@@ -789,7 +787,6 @@ I am bar.
789
787
I am bar.
790
788
I am bar.
791
789
I am r.
792
-
I am B.
793
790
</screen>
794
791
</example>
795
792
</para>
...
...
@@ -833,7 +830,7 @@ I am B.
833
830
</para>
834
831
835
832
<para>
836
-
As of PHP 5.4.0, there are only two ways to access data from your HTML forms.
833
+
There are only two ways to access data from your HTML forms.
837
834
Currently available methods are listed below:
838
835
</para>
839
836
...
...
@@ -852,32 +849,6 @@ echo $_REQUEST['username'];
852
849
</para>
853
850
854
851
<para>
855
-
There were some other ways of accessing user input in old PHP versions. There
856
-
are listed below. See changelog at the bottom of the page for more details.
857
-
<example>
858
-
<title>Old methods of accessing user input</title>
859
-
<programlisting role="php">
860
-
<![CDATA[
861
-
<?php
862
-
// WATCH OUT: these methods ARE NOT supported anymore.
863
-
// Valid ones were described above.
864
-
865
-
// Using import_request_variables() - this function has been removed in PHP 5.4.0
866
-
import_request_variables('p', 'p_');
867
-
echo $p_username;
868
-
869
-
// These long predefined variables were removed in PHP 5.4.0
870
-
echo $HTTP_POST_VARS['username'];
871
-
872
-
// Using register_globals. This feature was removed in PHP 5.4.0
873
-
echo $username;
874
-
?>
875
-
]]>
876
-
</programlisting>
877
-
</example>
878
-
</para>
879
-
880
-
<para>
881
852
Using a GET form is similar except you'll use the appropriate
882
853
GET predefined variable instead. GET also applies to the
883
854
<literal>QUERY_STRING</literal> (the information after the '?' in a URL). So,
...
...
@@ -931,6 +902,14 @@ if ($_POST) {
931
902
</example>
932
903
</para>
933
904
905
+
<note>
906
+
<simpara>
907
+
If an external variable name begins with a valid array syntax, trailing characters
908
+
are silently ignored. For example, <literal><input name="foo[bar]baz"></literal>
909
+
becomes <literal>$_REQUEST['foo']['bar']</literal>.
910
+
</simpara>
911
+
</note>
912
+
934
913
<sect3 xml:id="language.variables.external.form.submit">
935
914
<title>IMAGE SUBMIT variable names</title>
936
915
...
...
@@ -979,6 +958,13 @@ if ($_POST) {
979
958
examples.
980
959
</simpara>
981
960
961
+
<note>
962
+
<simpara>
963
+
As of PHP 7.2.34, 7.3.23 and 7.4.11, respectively, the <emphasis>names</emphasis>
964
+
of incoming cookies are no longer url-decoded for security reasons.
965
+
</simpara>
966
+
</note>
967
+
982
968
<simpara>
983
969
If you wish to assign multiple values to a single cookie variable, you
984
970
may assign it as an array. For example:
...
...
@@ -1072,6 +1058,19 @@ $varname.ext; /* invalid variable name */
1072
1058
<function>is_string</function>. See also the chapter on
1073
1059
<link linkend="language.types">Types</link>.
1074
1060
</para>
1061
+
<para>
1062
+
HTTP being a text protocol, most, if not all, content that comes in
1063
+
<link linkend="language.variables.superglobals">Superglobal arrays</link>,
1064
+
like <varname>$_POST</varname> and <varname>$_GET</varname> will remain
1065
+
as strings. PHP will not try to convert values to a specific type.
1066
+
In the example below, <varname>$_GET["var1"]</varname> will contain the
1067
+
string "null" and <varname>$_GET["var2"]</varname>, the string "123".
1068
+
<programlisting>
1069
+
<![CDATA[
1070
+
/index.php?var1=null&var2=123
1071
+
]]>
1072
+
</programlisting>
1073
+
</para>
1075
1074
</sect2>
1076
1075
1077
1076
<sect2 xml:id="language.variables.external.changelog">
...
...
@@ -1088,36 +1087,10 @@ $varname.ext; /* invalid variable name */
1088
1087
</thead>
1089
1088
<tbody>
1090
1089
<row>
1091
-
<entry>5.4.0</entry>
1092
-
<entry>
1093
-
<link linkend="security.globals">Register Globals</link>,
1094
-
<link linkend="security.magicquotes">Magic Quotes</link> and
1095
-
<link linkend="ini.register-long-arrays">register_long_arrays</link>
1096
-
has been removed
1097
-
</entry>
1098
-
</row>
1099
-
<row>
1100
-
<entry>5.3.0</entry>
1101
-
<entry>
1102
-
<link linkend="security.globals">Register Globals</link>,
1103
-
<link linkend="security.magicquotes">Magic Quotes</link> and
1104
-
<link linkend="ini.register-long-arrays">register_long_arrays</link>
1105
-
became deprecated
1106
-
</entry>
1107
-
</row>
1108
-
<row>
1109
-
<entry>4.2.0</entry>
1110
-
<entry>
1111
-
<link linkend="ini.register-globals">register_globals</link>
1112
-
directive defaults to <emphasis>off</emphasis>.
1113
-
</entry>
1114
-
</row>
1115
-
<row>
1116
-
<entry>4.1.0</entry>
1090
+
<entry>7.2.34, 7.3.23, 7.4.11</entry>
1117
1091
<entry>
1118
-
<link linkend="language.variables.superglobals">Superglobal arrays</link>,
1119
-
like <varname>$_POST</varname> and <varname>$_GET</varname> became
1120
-
available
1092
+
The <emphasis>names</emphasis> of incoming cookies are no longer url-decoded
1093
+
for security reasons.
1121
1094
</entry>
1122
1095
</row>
1123
1096
</tbody>
1124
1097