language/references.xml
9463e5b660c4883b91a30f07ff68731bbcc48346
9463e5b660c4883b91a30f07ff68731bbcc48346
...
...
@@ -11,9 +11,10 @@
11
11
you cannot perform pointer arithmetic using them, they are not
12
12
actual memory addresses, and so on. See
13
13
<xref linkend="language.references.arent" /> for more
14
-
information. Instead, they are symbol table aliases. Note that in
15
-
PHP, variable name and variable content are different, so the same
16
-
content can have different names. The closest analogy is with
14
+
information. Instead, they are
15
+
<link linkend="features.gc.refcounting-basics">symbol table</link>
16
+
aliases. Note that in PHP, variable name and variable content are different, so the same
17
+
content can have different names. The closest analogy is with
17
18
Unix filenames and files - variable names are directory entries,
18
19
while variable content is the file itself. References can be
19
20
likened to hardlinking in Unix filesystem.
...
...
@@ -40,7 +41,9 @@
40
41
<programlisting role="php">
41
42
<![CDATA[
42
43
<?php
44
+
43
45
$a =& $b;
46
+
44
47
?>
45
48
]]>
46
49
</programlisting>
...
...
@@ -66,7 +69,8 @@ $a =& $b;
66
69
<programlisting role="php">
67
70
<![CDATA[
68
71
<?php
69
-
function foo(&$var) { }
72
+
73
+
function foo(&$var) {}
70
74
71
75
foo($a); // $a is "created" and assigned to null
72
76
...
...
@@ -74,9 +78,10 @@ $b = array();
74
78
foo($b['b']);
75
79
var_dump(array_key_exists('b', $b)); // bool(true)
76
80
77
-
$c = new StdClass;
81
+
$c = new stdClass();
78
82
foo($c->d);
79
83
var_dump(property_exists($c, 'd')); // bool(true)
84
+
80
85
?>
81
86
]]>
82
87
</programlisting>
...
...
@@ -90,15 +95,20 @@ var_dump(property_exists($c, 'd')); // bool(true)
90
95
<programlisting role="php">
91
96
<![CDATA[
92
97
<?php
98
+
93
99
$foo =& find_var($bar);
100
+
94
101
?>
95
102
]]>
96
103
</programlisting>
97
104
</informalexample>
98
-
<link linkend="language.oop5.basic.new">new</link>
99
-
returns a reference automatically, thus it is syntactically invalid.
100
-
For more information, see <link linkend="language.oop5.references">Objects
101
-
and references</link>.)
105
+
</para>
106
+
<para>
107
+
Using the same syntax with a function that does <emphasis>not</emphasis>
108
+
return by reference will give an error, as will using it with the result
109
+
of the <link linkend="language.oop5.basic.new">new</link> operator.
110
+
Although objects are passed around as pointers, these are not the same as references,
111
+
as explained under <link linkend="language.oop5.references">Objects and references</link>.
102
112
</para>
103
113
<warning>
104
114
<para>
...
...
@@ -110,12 +120,14 @@ $foo =& find_var($bar);
110
120
<programlisting role="php">
111
121
<![CDATA[
112
122
<?php
123
+
113
124
$var1 = "Example variable";
114
125
$var2 = "";
115
126
116
127
function global_references($use_globals)
117
128
{
118
129
global $var1, $var2;
130
+
119
131
if (!$use_globals) {
120
132
$var2 =& $var1; // visible only inside the function
121
133
} else {
...
...
@@ -125,8 +137,10 @@ function global_references($use_globals)
125
137
126
138
global_references(false);
127
139
echo "var2 is set to '$var2'\n"; // var2 is set to ''
140
+
128
141
global_references(true);
129
142
echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
143
+
130
144
?>
131
145
]]>
132
146
</programlisting>
...
...
@@ -145,12 +159,16 @@ echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
145
159
<programlisting role="php">
146
160
<![CDATA[
147
161
<?php
162
+
148
163
$ref = 0;
149
164
$row =& $ref;
165
+
150
166
foreach (array(1, 2, 3) as $row) {
151
-
// do something
167
+
// Do something
152
168
}
169
+
153
170
echo $ref; // 3 - last element of the iterated array
171
+
154
172
?>
155
173
]]>
156
174
</programlisting>
...
...
@@ -167,11 +185,16 @@ echo $ref; // 3 - last element of the iterated array
167
185
<programlisting role="php">
168
186
<![CDATA[
169
187
<?php
188
+
170
189
$a = 1;
171
190
$b = array(2, 3);
191
+
172
192
$arr = array(&$a, &$b[0], &$b[1]);
173
-
$arr[0]++; $arr[1]++; $arr[2]++;
193
+
$arr[0]++;
194
+
$arr[1]++;
195
+
$arr[2]++;
174
196
/* $a == 2, $b == array(3, 4); */
197
+
175
198
?>
176
199
]]>
177
200
</programlisting>
...
...
@@ -187,19 +210,21 @@ $arr[0]++; $arr[1]++; $arr[2]++;
187
210
<programlisting role="php">
188
211
<![CDATA[
189
212
<?php
213
+
190
214
/* Assignment of scalar variables */
191
215
$a = 1;
192
216
$b =& $a;
193
217
$c = $b;
194
-
$c = 7; //$c is not a reference; no change to $a or $b
218
+
$c = 7; // $c is not a reference; no change to $a or $b
195
219
196
220
/* Assignment of array variables */
197
221
$arr = array(1);
198
-
$a =& $arr[0]; //$a and $arr[0] are in the same reference set
199
-
$arr2 = $arr; //not an assignment-by-reference!
222
+
$a =& $arr[0]; // $a and $arr[0] are in the same reference set
223
+
$arr2 = $arr; // Not an assignment-by-reference!
200
224
$arr2[0]++;
201
225
/* $a == 2, $arr == array(2) */
202
226
/* The contents of $arr are changed even though it's not a reference! */
227
+
203
228
?>
204
229
]]>
205
230
</programlisting>
...
...
@@ -220,6 +245,7 @@ $arr2[0]++;
220
245
<programlisting role="php">
221
246
<![CDATA[
222
247
<?php
248
+
223
249
function foo(&$var)
224
250
{
225
251
$var++;
...
...
@@ -227,6 +253,7 @@ function foo(&$var)
227
253
228
254
$a=5;
229
255
foo($a);
256
+
230
257
?>
231
258
]]>
232
259
</programlisting>
...
...
@@ -257,11 +284,14 @@ foo($a);
257
284
<programlisting role="php">
258
285
<![CDATA[
259
286
<?php
287
+
260
288
function foo(&$var)
261
289
{
262
290
$var =& $GLOBALS["baz"];
263
291
}
292
+
264
293
foo($bar);
294
+
265
295
?>
266
296
]]>
267
297
</programlisting>
...
...
@@ -277,7 +307,7 @@ foo($bar);
277
307
available in the function <varname>foo</varname> (it is represented by
278
308
<varname>$var</varname>, but <varname>$var</varname> has only
279
309
variable contents and not name-to-value binding in the calling
280
-
symbol table).
310
+
<link linkend="features.gc.refcounting-basics">symbol table</link>).
281
311
You can use <link linkend="language.references.return">returning
282
312
references</link> to reference variables selected by the function.
283
313
</simpara>
...
...
@@ -292,14 +322,17 @@ foo($bar);
292
322
<programlisting role="php">
293
323
<![CDATA[
294
324
<?php
325
+
295
326
function foo(&$var)
296
327
{
297
328
$var++;
298
329
}
299
330
300
331
$a=5;
332
+
301
333
foo($a);
302
334
// $a is 6 here
335
+
303
336
?>
304
337
]]>
305
338
</programlisting>
...
...
@@ -327,16 +360,20 @@ foo($a);
327
360
<programlisting role="php">
328
361
<![CDATA[
329
362
<?php
363
+
330
364
function foo(&$var)
331
365
{
332
366
$var++;
333
367
}
368
+
334
369
function &bar()
335
370
{
336
371
$a = 5;
337
372
return $a;
338
373
}
374
+
339
375
foo(bar());
376
+
340
377
?>
341
378
]]>
342
379
</programlisting>
...
...
@@ -355,26 +392,28 @@ foo(bar());
355
392
<programlisting role="php">
356
393
<![CDATA[
357
394
<?php
395
+
358
396
function foo(&$var)
359
397
{
360
398
$var++;
361
399
}
400
+
362
401
function bar() // Note the missing &
363
402
{
364
403
$a = 5;
365
404
return $a;
366
405
}
406
+
367
407
foo(bar()); // Produces a notice
368
408
369
409
foo($a = 5); // Expression, not variable
370
410
foo(5); // Produces fatal error
371
411
372
-
class Foobar
373
-
{
374
-
}
412
+
class Foobar {}
375
413
376
414
foo(new Foobar()) // Produces a notice as of PHP 7.0.7
377
415
// Notice: Only variables should be passed by reference
416
+
378
417
?>
379
418
]]>
380
419
</programlisting>
...
...
@@ -395,18 +434,22 @@ foo(new Foobar()) // Produces a notice as of PHP 7.0.7
395
434
<programlisting role="php">
396
435
<![CDATA[
397
436
<?php
398
-
class foo {
437
+
438
+
class Foo
439
+
{
399
440
public $value = 42;
400
441
401
-
public function &getValue() {
442
+
public function &getValue()
443
+
{
402
444
return $this->value;
403
445
}
404
446
}
405
447
406
-
$obj = new foo;
407
-
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42.
448
+
$obj = new Foo();
449
+
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42
408
450
$obj->value = 2;
409
-
echo $myValue; // prints the new value of $obj->value, i.e. 2.
451
+
echo $myValue; // Prints the new value of $obj->value, i.e. 2
452
+
410
453
?>
411
454
]]>
412
455
</programlisting>
...
...
@@ -439,27 +482,49 @@ echo $myValue; // prints the new value of $obj->value, i.e. 2.
439
482
<programlisting role="php">
440
483
<![CDATA[
441
484
<?php
442
-
function &collector() {
443
-
static $collection = array();
444
-
return $collection;
485
+
486
+
function &collector()
487
+
{
488
+
static $collection = array();
489
+
return $collection;
445
490
}
491
+
446
492
$collection = &collector();
493
+
// Now the $collection is a referenced variable that references the static array inside the function
494
+
447
495
$collection[] = 'foo';
496
+
497
+
print_r(collector());
498
+
// Array
499
+
// (
500
+
// [0] => foo
501
+
// )
502
+
448
503
?>
449
504
]]>
450
505
</programlisting>
451
506
</informalexample>
507
+
<note>
508
+
<simpara>
509
+
If the assignment is done without the <literal>&</literal> symbol, e.g. <code>$collection = collector();</code>,
510
+
the <varname>$collection</varname> variable will receive a copy of the value, not the reference returned by the function.
511
+
</simpara>
512
+
</note>
452
513
To pass the returned reference to another function expecting a reference
453
514
you can use this syntax:
454
515
<informalexample>
455
516
<programlisting role="php">
456
517
<![CDATA[
457
518
<?php
458
-
function &collector() {
459
-
static $collection = array();
460
-
return $collection;
519
+
520
+
function &collector()
521
+
{
522
+
static $collection = array();
523
+
return $collection;
461
524
}
525
+
462
526
array_push(collector(), 'foo');
527
+
463
528
?>
464
529
]]>
465
530
</programlisting>
...
...
@@ -483,9 +548,11 @@ array_push(collector(), 'foo');
483
548
<programlisting role="php">
484
549
<![CDATA[
485
550
<?php
551
+
486
552
$a = 1;
487
553
$b =& $a;
488
554
unset($a);
555
+
489
556
?>
490
557
]]>
491
558
</programlisting>
...
...
@@ -518,7 +585,9 @@ unset($a);
518
585
<programlisting role="php">
519
586
<![CDATA[
520
587
<?php
588
+
521
589
$var =& $GLOBALS["var"];
590
+
522
591
?>
523
592
]]>
524
593
</programlisting>
...
...
@@ -529,14 +598,6 @@ $var =& $GLOBALS["var"];
529
598
won't unset the global variable.
530
599
</simpara>
531
600
</sect2>
532
-
533
-
<sect2 xml:id="references.this">
534
-
<title><literal>$this</literal></title>
535
-
<simpara>
536
-
In an object method, <varname>$this</varname> is always a reference
537
-
to the called object.
538
-
</simpara>
539
-
</sect2>
540
601
</sect1>
541
602
542
603
</chapter>
543
604