|  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #69321 Please clarify when users should design functions for pass-by-reference
Submitted: 2015-03-28 19:33 UTC Modified: 2018-01-31 10:31 UTC
From: php at richardneill dot org Assigned:
Status: Open Package: Scripting Engine problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2015-03-28 19:33 UTC] php at richardneill dot org
I think it would be worth clarifying when it is necessary to use pass-by-reference vs pass-by-value. The script below shows that:  PHP already optimises pass-by-value function calls to do zero-copy (or copy-on-write) regardless of whether the function definition contains a by-reference instruction.

Also, it would be helpful to explain why call-time-pass-by-reference is not allowed [I can see cases where a function that works normally by-value could sometimes be called by-reference.]  Lastly, why can't we have the "&" in the function call, even if it is mere syntactic sugar? It's otherwise a source of code-unreadability. 

Test script:
function sum($array,$max){   //For Reference, use:  "&$array"
    for ($i=0; $i<2; $i++){
        #$array[$i]++;        //Uncomment this line to modify the array within the function.
        $sum += $array[$i];
    return ($sum);

$max = 1E7                  //10 M data points.
$data = range(0,$max,1);

$start = microtime(true);
for ($x = 0 ; $x < 100; $x++){
    $sum = sum($data, $max);
$end =  microtime(true);
echo "Time: ".($end - $start)." s\n";


Actual result:
Measured Run times:
#    PASS BY    MODIFIED?   Time
-    -------    ---------   ----
1    value      no          56 us
2    reference  no          58 us

3    valuue     yes         129 s
4    reference  yes         66 us


1. PHP is already smart about zero-copy / copy-on-write. A function call does NOT copy the data unless it needs to; the data is
   only copied on write. That's why  #1 and #2 take similar times, whereas #3 takes 2 million times longer than #4.
   [You never need to use &$array to ask the compiler to do a zero-copy optimisation; it can work that out for itself.]

2. You do use &$array  to tell the compiler "it is OK for the function to over-write my argument in place, I don't need the original
   any more." This can make a huge difference to performance when we have large amounts of memory to copy.
   (This is the only way it is done in C, arrays are always passed as pointers)

3. The other use of & is as a way to specify where data should be *returned*. (eg as used by exec() ).
   (This is a C-like way of passing pointers for outputs, whereas PHP functions normally return complex types, or multiple answers
   in an array)

4. It's  unhelpful that only the function definition has &. The caller should have it, at least as syntactic sugar. Otherwise
   it leads to unreadable code: because the person reading the function call doesn't expect it to pass by reference. At the moment,
   it's necessary to write a function call with a comment, thus:
	$sum = sum($data,$max);  //warning, $data passed by reference, and may be modified.

5. Sometimes, pass by reference could be at the choice of the caller, NOT the function definition. PHP doesn't allow it, but it
   would be meaningful for the caller to decide to pass data in as a reference. i.e. "I'm done with the variable, it's OK to stomp
   on it in memory".


Add a Patch

Pull Requests

Add a Pull Request


AllCommentsChangesGit/SVN commitsRelated reports
 [2018-01-31 10:31 UTC]
-Type: Feature/Change Request +Type: Documentation Problem -Package: Documentation problem +Package: Scripting Engine problem
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Jul 18 20:01:28 2024 UTC