133

I'm using the Facebook library with this code in it:

class FacebookRestClient {
...
    public function &users_hasAppPermission($ext_perm, $uid=null) {
        return $this->call_method('facebook.users.hasAppPermission', 
        array('ext_perm' => $ext_perm, 'uid' => $uid));
    }
...
}

What does the & at the beginning of the function definition mean, and how do I go about using a library like this (in a simple example)

Peter O.
  • 28,965
  • 14
  • 72
  • 87
Alex Mcp
  • 17,682
  • 12
  • 56
  • 87

3 Answers3

161

An ampersand before a function name means the function will return a reference to a variable instead of the value.

Returning by reference is useful when you want to use a function to find to which variable a reference should be bound. Do not use return-by-reference to increase performance. The engine will automatically optimize this on its own. Only return references when you have a valid technical reason to do so.

See Returning References.

KingCrunch
  • 119,075
  • 18
  • 142
  • 167
Dominic Rodger
  • 90,548
  • 30
  • 192
  • 207
  • 1
    So, without going into too detail, you would call (with the class instantiated) something like $results = $facebook->users_hasAppPermission($param1, $param2); ? I guess I'm not sure of the nuance here, thanks for the help though. – Alex Mcp Nov 04 '09 at 21:56
  • 2
    Yep - I'd just call it like that. – Dominic Rodger Nov 04 '09 at 22:19
17

It's returning a reference, as mentioned already. In PHP 4, objects were assigned by value, just like any other value. This is highly unintuitive and contrary to how most other languages works.

To get around the problem, references were used for variables that pointed to objects. In PHP 5, references are very rarely used. I'm guessing this is legacy code or code trying to preserve backwards compatibility with PHP 4.

Peter Mortensen
  • 28,342
  • 21
  • 95
  • 123
troelskn
  • 107,146
  • 23
  • 127
  • 148
  • It's the official Facebook PHP library, FWIW. – Alex Mcp Nov 04 '09 at 22:01
  • Info on the new PHP 5 Object Model (as opposed to the old pass-by-value nonsense (and other nonsense) from PHP4): http://php.net/manual/en/migration5.oop.php – Dereleased Nov 04 '09 at 22:34
  • 4
    @Alex: In that case, they're probably doing it to protect casual hackers, who use php4, from them selves. You shouldn't do this in your own code - It's deprecated. – troelskn Nov 04 '09 at 22:36
  • 3
    "This is highly unintuitive and contrary to how most other languages works" I couldn't disagree more. – Lightness Races in Orbit Aug 01 '11 at 14:52
  • @LightnessRacesinOrbit care to elaborate? – WildlyInaccurate Dec 04 '12 at 16:17
  • 5
    @WildlyInaccurate: Assigning objects by reference by default, which is what happens in .NET and in Java (I think), is highly unintuitive. In most other languages, assignment is done by copy, whether you have an "object" or a primitive or whatever, and since this has been the case since the dawn of time, this is what the world ought to have stuck to. – Lightness Races in Orbit Dec 04 '12 at 17:29
  • 4
    Whether something is intuitive is probably rather subjective. But for languages that are otherwise similar to PHP, the norm is to pass objects by reference. In regards to OOP, I would say that is the most intuitive way, since OOP is about encapsulating state, so programs would usually refer to that state, rather than cloning it. – troelskn Dec 05 '12 at 00:04
5

This is often known in PHP as Returning reference or Returning by reference.

Returning by reference is useful when you want to use a function to find to which variable a reference should be bound. Do not use return-by-reference to increase performance. The engine will automatically optimize this on its own. Only return references when you have a valid technical reason to do so.

PHP documentation on Returning reference

A reference in PHP is simply another name assigned to the content of a variable. PHP references are not like pointers in C programming, they are not actual memory addresses, so they cannot be used for pointer arithmetics.

The concept of returning references can be very confusing especially to beginners, so an example will be helpful.

$populationCount = 120;

function &getPopulationCount() {
  global $populationCount;
  return $populationCount;
}

$countryPopulation =& getPopulationCount();
$countryPopulation++;
echo "\$populationCount = $populationCount\n"; // Output: $populationCount = 121 
echo "\$countryPopulation = $countryPopulation\n"; //Output: $countryPopulation = 121

The function getPopulationCount() defined with a preceding &, returns the reference to the content or value of $populationCount. So, incrementing $countryPopulation, also increments $populationCount.

Elisha Senoo
  • 3,019
  • 2
  • 20
  • 28