#41992 [Opn->Csd]: __sleep documentation is incorrect

ID: 41992 Updated by: colder@php.net Reported By: jsnell at e-normous dot com -Status: Open +Status: Closed Bug Type: Documentation problem Operating System: OSX 10.4.10 PHP Version: Irrelevant -Assigned To: +Assigned To: colder New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Thanks for the patch Previous Comments: ------------------------------------------------------------------------ [2007-07-13 17:46:46] jsnell at e-normous dot com Description: ------------ Referencing, http://us2.php.net/manual/en/language.oop5.magic.php, Two statements conflict with each other: "serialize() checks if your class has a function with the magic name __sleep. If so, that function is executed prior to any serialization. It can clean up the object and is supposed to return an array with the names of all variables of that object that should be serialized. If the method doesn't return anything then NULL is serialized and E_NOTICE is issued." and: "The __sleep method should return the value to serialize (usually $this), otherwise NULL is serialized." Reproduce code: --------------- As per the second statement: class foo { public $stuff =1; function __sleep() { return $this; } } error_reporting(E_ALL); $bar = new foo(); serialize($bar); causes the notice: "serialize() [function.serialize]: __sleep should return an array only containing the names of instance-variables to serialize." Further, the notice does not appear if the class has no attributes: class foo { function __sleep() { return $this; } } error_reporting(E_ALL); $bar = new foo(); serialize($bar); Expected result: ---------------- If returning an object used to be the proper way to do this, a notice which states that returning an object is deprecated. If not, then the documentation should not state that returning $this is valid. Here is patch for the latter: cvs diff -u en/language/oop5/magic.xml Index: en/language/oop5/magic.xml =================================================================== RCS file: /repository/phpdoc/en/language/oop5/magic.xml,v retrieving revision 1.15 diff -u -u -r1.15 magic.xml --- en/language/oop5/magic.xml 20 Jun 2007 22:24:13 -0000 1.15 +++ en/language/oop5/magic.xml 13 Jul 2007 17:43:06 -0000 @@ -51,10 +51,6 @@ saved completely. </para> <para> - The <literal>__sleep</literal> method should return the value to serialize - (usually <literal>$this</literal>), otherwise &null; is serialized. - </para> - <para> Conversely, <function>unserialize</function> checks for the presence of a function with the magic name <literal>__wakeup</literal>. If present, this function can Actual result: -------------- None, since this code based on incorrect documentation should not be run in the first place. ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=41992&edit=1