#49147 [NEW]: "What references do" docs are incorrect

From: initcontact at grahamwideman dot com Operating system: PHP version: Irrelevant PHP Bug Type: Documentation problem Bug description: "What references do" docs are incorrect Description: ------------ This text: "Since PHP 5, new returns a reference automatically, so using =& in this context is deprecated and produces an E_STRICT message. Note: Not using the & operator causes a copy of the object to be made." ... and following text is incorrect. It was probably intended to refer to the way PHP 4 used to work (but even then is not really correct.) Reproduce code: --------------- --- From manual page: language.references.whatdo --- http://www.php.net/manual/en/language.references.whatdo.php Expected result: ---------------- Issues: 1. "Since PHP 5, new returns a reference automatically" What I think is correct: Since PHP 5, *in general* functions that return an object return it as an *object Id*. This works like what some other languages call a "reference", but in PHP the word "reference" refers to something more like an alias. (See: http://www.php.net/manual/en/language.oop5.references.php). 2. "Not using the & operator causes a copy of the object to be made." I guess that was true in PHP 4. In PHP 5, in the following code the plain "=" copies the object id: $a1 = new A(); $a2 = $a1; $a1->somemember = 3; print $a2->somemember ; // prints 3 ... and consequently $a2-> accesses same object as $a1->. 3. The comments on $this are problematic. I think it's just saying the obvious, that $this operates on the particular object on which the member was invoked. 4. "Usually you want to have a single instance to work with, due to performance and memory consumption issues." That seems like a red herring -- a programmer chooses to have one instance or several instances because they either want a single collection of data, or they want multiple similar-structured collections of data. If the programmer wanted a single instance, but accidentally created several, then that's a logical problem before it's a performance problem (and vice versa). Hope that's all clear, -- Graham -- Edit bug report at http://bugs.php.net/?id=49147&edit=1 -- Try a snapshot (PHP 5.2): http://bugs.php.net/fix.php?id=49147&r=trysnapshot52 Try a snapshot (PHP 5.3): http://bugs.php.net/fix.php?id=49147&r=trysnapshot53 Try a snapshot (PHP 6.0): http://bugs.php.net/fix.php?id=49147&r=trysnapshot60 Fixed in SVN: http://bugs.php.net/fix.php?id=49147&r=fixed Fixed in SVN and need be documented: http://bugs.php.net/fix.php?id=49147&r=needdocs Fixed in release: http://bugs.php.net/fix.php?id=49147&r=alreadyfixed Need backtrace: http://bugs.php.net/fix.php?id=49147&r=needtrace Need Reproduce Script: http://bugs.php.net/fix.php?id=49147&r=needscript Try newer version: http://bugs.php.net/fix.php?id=49147&r=oldversion Not developer issue: http://bugs.php.net/fix.php?id=49147&r=support Expected behavior: http://bugs.php.net/fix.php?id=49147&r=notwrong Not enough info: http://bugs.php.net/fix.php?id=49147&r=notenoughinfo Submitted twice: http://bugs.php.net/fix.php?id=49147&r=submittedtwice register_globals: http://bugs.php.net/fix.php?id=49147&r=globals PHP 4 support discontinued: http://bugs.php.net/fix.php?id=49147&r=php4 Daylight Savings: http://bugs.php.net/fix.php?id=49147&r=dst IIS Stability: http://bugs.php.net/fix.php?id=49147&r=isapi Install GNU Sed: http://bugs.php.net/fix.php?id=49147&r=gnused Floating point limitations: http://bugs.php.net/fix.php?id=49147&r=float No Zend Extensions: http://bugs.php.net/fix.php?id=49147&r=nozend MySQL Configuration Error: http://bugs.php.net/fix.php?id=49147&r=mysqlcfg