[PHP-DOC] cvs: phpdoc /en/reference/expect/functions expect-expectl.xml

2006-07-04 Thread Michael Spector
michael Tue Jul  4 08:26:08 2006 UTC

  Modified files:  
/phpdoc/en/reference/expect/functions   expect-expectl.xml 
  Log:
  Fix function prototype, according to latest changes.
  
  
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/expect/functions/expect-expectl.xml?r1=1.7r2=1.8diff_format=u
Index: phpdoc/en/reference/expect/functions/expect-expectl.xml
diff -u phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7 
phpdoc/en/reference/expect/functions/expect-expectl.xml:1.8
--- phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7 Tue Mar  7 
12:07:16 2006
+++ phpdoc/en/reference/expect/functions/expect-expectl.xml Tue Jul  4 
08:26:08 2006
@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.7 $ --
+!-- $Revision: 1.8 $ --
 refentry id=function.expect-expectl
  refnamediv
   refnameexpect_expectl/refname
@@ -13,15 +13,18 @@
typemixed/typemethodnameexpect_expectl/methodname

methodparamtyperesource/typeparameterexpect/parameter/methodparam
methodparamtypearray/typeparametercases/parameter/methodparam
-   methodparamtypestring/typeparameter 
role=referencematch/parameter/methodparam
+   methodparamtypearray/typeparameter 
role=referencematch/parameter/methodparam
   /methodsynopsis
   para
Waits until the output from a process matches one of the patterns,
a specified time period has passed, or an EOF is seen.
   /para
   para
-   If parametermatch/parameter is provided, then it is filled with the
-   result of search.
+   If parametermatch/parameter is provided, then it is filled with the 
result of search.
+   The matched string can be found in parametermatch[0]/parameter.
+   The match substrings (according to the parentheses) in the original pattern 
can be found
+   in parametermatch[1]/parameter, parametermatch[2]/parameter, and so
+   on, up to parametermatch[9]/parameter (the limitation of libexpect).
   /para
  /refsect1
  refsect1 role=parameters


[PHP-DOC] cvs: phpdoc /en/reference/mysql/functions mysql-info.xml

2006-07-04 Thread Horst Schirmeier
hsc Tue Jul  4 10:29:34 2006 UTC

  Modified files:  
/phpdoc/en/reference/mysql/functionsmysql-info.xml 
  Log:
  style; missing period added
  
  
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mysql/functions/mysql-info.xml?r1=1.9r2=1.10diff_format=u
Index: phpdoc/en/reference/mysql/functions/mysql-info.xml
diff -u phpdoc/en/reference/mysql/functions/mysql-info.xml:1.9 
phpdoc/en/reference/mysql/functions/mysql-info.xml:1.10
--- phpdoc/en/reference/mysql/functions/mysql-info.xml:1.9  Thu Mar 31 
07:47:25 2005
+++ phpdoc/en/reference/mysql/functions/mysql-info.xml  Tue Jul  4 10:29:34 2006
@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.9 $ --
+!-- $Revision: 1.10 $ --
 refentry id=function.mysql-info
  refnamediv
   refnamemysql_info/refname
@@ -31,8 +31,8 @@
   para
Returns information about the statement on success, or false; on
failure. See the example below for which statements provide information,
-   and what the returned value may look like. Statements that aren't listed 
-   will return false;
+   and what the returned value may look like. Statements that are not listed 
+   will return false;.
   /para
  /refsect1
 



[PHP-DOC] ext/mysql return types

2006-07-04 Thread Horst Schirmeier
Hi,

I just noticed that the return types of some ext/mysql functions are not
correct, or at least misleading.


1) mixed return values in normal usage


In the description of mysql_query(), the interface is shown as
follows:

resource mysql_query ( string query [, resource link_identifier] )

But the Return Values section makes clear that the return type could
also be a boolean; shouldn't the return type be mixed instead of
resource, as for example in the documentation to mysqli_query() -- or
has this been documented this way for a reason?

All ext/mysql functions which return mixed types but are not
properly documented to do so:
* mysql_query
* mysql_db_query
* mysql_fetch_array
* mysql_fetch_assoc
* mysql_fetch_field (here the docs even lack or FALSE if there are no
  more rows in the Return Values section)
* mysql_fetch_object
* mysql_fetch_row
* mysql_unbuffered_query


2) mixed return values on error paths
---

Similarly this is true for mysql_connect(), although here FALSE is only
returned on failure; the normal return type is resource. Is this
intentional, or should it also be corrected to mixed? (I'd vote for
the former.)

All ext/mysql functions which return FALSE on failure but are not
documented to do so in the Description:
mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags,
mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type,
mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info,
mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields,
mysql_list_processes, mysql_list_tables, mysql_num_fields,
mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result,
mysql_stat (returns NULL on failure, not FALSE), mysql_tablename,
mysql_thread_id.


3) minor corrections


Beyond this,
* mysql_field_seek needs a Return Values section (although it is
  intuitive that it returns TRUE on success and FALSE on failure).
* mysql_field_table and mysql_field_type need returns FALSE on failure
  to be documented.


Any comments/objections to these corrections? If nobody vetoes, I would
starting to fix 1) and 3) the next days.

Kind regards,
 Horst

-- 
PGP-Key 0xD40E0E7A


[PHP-DOC] cvs: phpdoc /en/reference/pgsql/functions pg-result-error.xml

2006-07-04 Thread Nuno Lopes
nlopess Tue Jul  4 11:13:25 2006 UTC

  Modified files:  
/phpdoc/en/reference/pgsql/functionspg-result-error.xml 
  Log:
  fix return value, per user note
  
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/pgsql/functions/pg-result-error.xml?r1=1.9r2=1.10diff_format=u
Index: phpdoc/en/reference/pgsql/functions/pg-result-error.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-result-error.xml:1.9 
phpdoc/en/reference/pgsql/functions/pg-result-error.xml:1.10
--- phpdoc/en/reference/pgsql/functions/pg-result-error.xml:1.9 Wed Nov 30 
04:06:54 2005
+++ phpdoc/en/reference/pgsql/functions/pg-result-error.xml Tue Jul  4 
11:13:25 2006
@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.9 $ --
+!-- $Revision: 1.10 $ --
 !-- splitted from ./en/functions/pgsql.xml, last change in rev 1.82 --
 refentry id='function.pg-result-error'
  refnamediv
@@ -53,7 +53,8 @@
  refsect1 role=returnvalues
   reftitle.returnvalues;
   para
-   return.success;
+   Returns a typestring/type if there is an error associated with the
+   parameterresult/parameter parameter, false; otherwise.
   /para
  /refsect1
  


[PHP-DOC] cvs: phpdoc /en/install ini.xml

2006-07-04 Thread Nuno Lopes
nlopess Tue Jul  4 11:03:22 2006 UTC

  Modified files:  
/phpdoc/en/install  ini.xml 
  Log:
  exchange the PHPRC var and the registry key order for php 5.2
  
http://cvs.php.net/viewvc.cgi/phpdoc/en/install/ini.xml?r1=1.13r2=1.14diff_format=u
Index: phpdoc/en/install/ini.xml
diff -u phpdoc/en/install/ini.xml:1.13 phpdoc/en/install/ini.xml:1.14
--- phpdoc/en/install/ini.xml:1.13  Thu May 11 09:38:23 2006
+++ phpdoc/en/install/ini.xml   Tue Jul  4 11:03:22 2006
@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.13 $ --
+!-- $Revision: 1.14 $ --
  chapter id=configuration
   titleRuntime Configuration/title
 
@@ -27,13 +27,14 @@
  /listitem
  listitem
   para
-   literalHKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath/literal
-   (Windows Registry location)
+   The varnamePHPRC/varname environment variable. Before PHP 5.2.0
+   this was checked after the registry key mentioned below.
   /para
  /listitem
  listitem
   para
-   The varnamePHPRC/varname environment variable
+   literalHKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath/literal
+   (Windows Registry location)
   /para
  /listitem
  listitem


Re: [PHP-DOC] ext/mysql return types

2006-07-04 Thread Nuno Lopes
The answer to your questions are answered in our howto. Mainly here: 
http://doc.php.net/php/dochowto/chapter-conventions.php


Quoting the important part (for now):
Do not use mixed, if the return value is of a certain (not boolean) type, 
and FALSE only on error. Provide the primary return type as the return type 
of the function, and write down in the explanation, that it returns FALSE on 
error. Use return.success; if the function returns TRUE on success, and 
FALSE on failure. 



Nuno


- Original Message - 

Hi,

I just noticed that the return types of some ext/mysql functions are not
correct, or at least misleading.


1) mixed return values in normal usage


In the description of mysql_query(), the interface is shown as
follows:

resource mysql_query ( string query [, resource link_identifier] )

But the Return Values section makes clear that the return type could
also be a boolean; shouldn't the return type be mixed instead of
resource, as for example in the documentation to mysqli_query() -- or
has this been documented this way for a reason?

All ext/mysql functions which return mixed types but are not
properly documented to do so:
* mysql_query
* mysql_db_query
* mysql_fetch_array
* mysql_fetch_assoc
* mysql_fetch_field (here the docs even lack or FALSE if there are no
 more rows in the Return Values section)
* mysql_fetch_object
* mysql_fetch_row
* mysql_unbuffered_query


2) mixed return values on error paths
---

Similarly this is true for mysql_connect(), although here FALSE is only
returned on failure; the normal return type is resource. Is this
intentional, or should it also be corrected to mixed? (I'd vote for
the former.)

All ext/mysql functions which return FALSE on failure but are not
documented to do so in the Description:
mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags,
mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type,
mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info,
mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields,
mysql_list_processes, mysql_list_tables, mysql_num_fields,
mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result,
mysql_stat (returns NULL on failure, not FALSE), mysql_tablename,
mysql_thread_id.


3) minor corrections


Beyond this,
* mysql_field_seek needs a Return Values section (although it is
 intuitive that it returns TRUE on success and FALSE on failure).
* mysql_field_table and mysql_field_type need returns FALSE on failure
 to be documented.


Any comments/objections to these corrections? If nobody vetoes, I would
starting to fix 1) and 3) the next days.

Kind regards,
Horst

--
PGP-Key 0xD40E0E7A 


Re: [PHP-DOC] ext/mysql return types

2006-07-04 Thread Horst Schirmeier
On Tue, 04 Jul 2006, Nuno Lopes wrote:
 The answer to your questions are answered in our howto. Mainly here: 
 http://doc.php.net/php/dochowto/chapter-conventions.php
 
 Quoting the important part (for now):
 Do not use mixed, if the return value is of a certain (not boolean) type, 
 and FALSE only on error. Provide the primary return type as the return type 
 of the function, and write down in the explanation, that it returns FALSE 
 on error. Use return.success; if the function returns TRUE on success, and 
 FALSE on failure. 

Oh, okay. Seems I missed this part. So 2) 'mixed return values on
error paths is clearly a no.

But what about 1) 'mixed return values in normal usage', for example
mysql_query(), which may return TRUE in normal usage? Or
mysql_fetch_array() which returns FALSE if there are no more rows --
should this be considered an error condition? At least the mysql_query()
issue confused someone on IRC today.

(Besides this, I still consider my corrections 3) as valid.)

Kind regards,
 Horst


 - Original Message - 
 Hi,
 
 I just noticed that the return types of some ext/mysql functions are not
 correct, or at least misleading.
 
 
 1) mixed return values in normal usage
 
 
 In the description of mysql_query(), the interface is shown as
 follows:
 
 resource mysql_query ( string query [, resource link_identifier] )
 
 But the Return Values section makes clear that the return type could
 also be a boolean; shouldn't the return type be mixed instead of
 resource, as for example in the documentation to mysqli_query() -- or
 has this been documented this way for a reason?
 
 All ext/mysql functions which return mixed types but are not
 properly documented to do so:
 * mysql_query
 * mysql_db_query
 * mysql_fetch_array
 * mysql_fetch_assoc
 * mysql_fetch_field (here the docs even lack or FALSE if there are no
  more rows in the Return Values section)
 * mysql_fetch_object
 * mysql_fetch_row
 * mysql_unbuffered_query
 
 
 2) mixed return values on error paths
 ---
 
 Similarly this is true for mysql_connect(), although here FALSE is only
 returned on failure; the normal return type is resource. Is this
 intentional, or should it also be corrected to mixed? (I'd vote for
 the former.)
 
 All ext/mysql functions which return FALSE on failure but are not
 documented to do so in the Description:
 mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags,
 mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type,
 mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info,
 mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields,
 mysql_list_processes, mysql_list_tables, mysql_num_fields,
 mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result,
 mysql_stat (returns NULL on failure, not FALSE), mysql_tablename,
 mysql_thread_id.
 
 
 3) minor corrections
 
 
 Beyond this,
 * mysql_field_seek needs a Return Values section (although it is
  intuitive that it returns TRUE on success and FALSE on failure).
 * mysql_field_table and mysql_field_type need returns FALSE on failure
  to be documented.
 
 
 Any comments/objections to these corrections? If nobody vetoes, I would
 starting to fix 1) and 3) the next days.
 
 Kind regards,
 Horst

-- 
PGP-Key 0xD40E0E7A


Re: [PHP-DOC] ext/mysql return types

2006-07-04 Thread Nuno Lopes

On Tue, 04 Jul 2006, Nuno Lopes wrote:

The answer to your questions are answered in our howto. Mainly here:
http://doc.php.net/php/dochowto/chapter-conventions.php

Quoting the important part (for now):
Do not use mixed, if the return value is of a certain (not boolean) 
type,
and FALSE only on error. Provide the primary return type as the return 
type

of the function, and write down in the explanation, that it returns FALSE
on error. Use return.success; if the function returns TRUE on success, 
and

FALSE on failure. 


Oh, okay. Seems I missed this part. So 2) 'mixed return values on
error paths is clearly a no.


yep


But what about 1) 'mixed return values in normal usage', for example
mysql_query(), which may return TRUE in normal usage? Or
mysql_fetch_array() which returns FALSE if there are no more rows --
should this be considered an error condition? At least the mysql_query()
issue confused someone on IRC today.


if the function returns different return types on normal usage you should 
use mixed. Don't forget to carefully document that.
(btw, while you are at it, you may consider upgrading the files you touch to 
the new doc style, which is simpler to maintain IMHO. take a look at 
http://wiki.phpdoc.info/DocSkel)



(Besides this, I still consider my corrections 3) as valid.)


yes, yes. see the link above.


Thanks for your contributions,
Nuno



Kind regards,
Horst


- Original Message - 
Hi,


I just noticed that the return types of some ext/mysql functions are not
correct, or at least misleading.


1) mixed return values in normal usage


In the description of mysql_query(), the interface is shown as
follows:

resource mysql_query ( string query [, resource link_identifier] )

But the Return Values section makes clear that the return type could
also be a boolean; shouldn't the return type be mixed instead of
resource, as for example in the documentation to mysqli_query() -- or
has this been documented this way for a reason?

All ext/mysql functions which return mixed types but are not
properly documented to do so:
* mysql_query
* mysql_db_query
* mysql_fetch_array
* mysql_fetch_assoc
* mysql_fetch_field (here the docs even lack or FALSE if there are no
 more rows in the Return Values section)
* mysql_fetch_object
* mysql_fetch_row
* mysql_unbuffered_query


2) mixed return values on error paths
---

Similarly this is true for mysql_connect(), although here FALSE is only
returned on failure; the normal return type is resource. Is this
intentional, or should it also be corrected to mixed? (I'd vote for
the former.)

All ext/mysql functions which return FALSE on failure but are not
documented to do so in the Description:
mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags,
mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type,
mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info,
mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields,
mysql_list_processes, mysql_list_tables, mysql_num_fields,
mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result,
mysql_stat (returns NULL on failure, not FALSE), mysql_tablename,
mysql_thread_id.


3) minor corrections


Beyond this,
* mysql_field_seek needs a Return Values section (although it is
 intuitive that it returns TRUE on success and FALSE on failure).
* mysql_field_table and mysql_field_type need returns FALSE on failure
 to be documented.


Any comments/objections to these corrections? If nobody vetoes, I would
starting to fix 1) and 3) the next days.

Kind regards,
Horst


--
PGP-Key 0xD40E0E7A



Re: [PHP-DOC] cvs: phpdoc /en/reference/expect/functions expect-expectl.xml

2006-07-04 Thread Michael Spector

Where should I add changelog?

Hannes Magnusson wrote:

On 7/4/06, Michael Spector [EMAIL PROTECTED] wrote:

michael Tue Jul  4 08:26:08 2006 UTC

  Modified files:
/phpdoc/en/reference/expect/functions   expect-expectl.xml
  Log:
  Fix function prototype, according to latest changes.


http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/expect/functions/expect-expectl.xml?r1=1.7r2=1.8diff_format=u 


Index: phpdoc/en/reference/expect/functions/expect-expectl.xml
diff -u phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7 
phpdoc/en/reference/expect/functions/expect-expectl.xml:1.8
--- phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7 Tue 
Mar  7 12:07:16 2006
+++ phpdoc/en/reference/expect/functions/expect-expectl.xml Tue 
Jul  4 08:26:08 2006

@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.7 $ --
+!-- $Revision: 1.8 $ --
 refentry id=function.expect-expectl
  refnamediv
   refnameexpect_expectl/refname
@@ -13,15 +13,18 @@
typemixed/typemethodnameexpect_expectl/methodname

methodparamtyperesource/typeparameterexpect/parameter/methodparam 


methodparamtypearray/typeparametercases/parameter/methodparam 

-   methodparamtypestring/typeparameter 
role=referencematch/parameter/methodparam
+   methodparamtypearray/typeparameter 
role=referencematch/parameter/methodparam


This is just evil. Why don't you add changelog?


--
Michael Spector, Software Developer
Zend Technologies +972-3-6139665 ext.223
ICQ: 7279639
AIM: spektom972
Yahoo: spektom
MSN: [EMAIL PROTECTED]


Re: [PHP-DOC] cvs: phpdoc /en/reference/expect/functions expect-expectl.xml

2006-07-04 Thread Hannes Magnusson

On 7/4/06, Michael Spector [EMAIL PROTECTED] wrote:

Where should I add changelog?


http://doc.php.net/php/dochowto/chapter-skeletons.php
See the first example.

Document the fact that prior to expect 0.2.1 $match was string, not an array...

-Hannes



Hannes Magnusson wrote:
 On 7/4/06, Michael Spector [EMAIL PROTECTED] wrote:
 michael Tue Jul  4 08:26:08 2006 UTC

   Modified files:
 /phpdoc/en/reference/expect/functions   expect-expectl.xml
   Log:
   Fix function prototype, according to latest changes.


 
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/expect/functions/expect-expectl.xml?r1=1.7r2=1.8diff_format=u

 Index: phpdoc/en/reference/expect/functions/expect-expectl.xml
 diff -u phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7
 phpdoc/en/reference/expect/functions/expect-expectl.xml:1.8
 --- phpdoc/en/reference/expect/functions/expect-expectl.xml:1.7 Tue
 Mar  7 12:07:16 2006
 +++ phpdoc/en/reference/expect/functions/expect-expectl.xml Tue
 Jul  4 08:26:08 2006
 @@ -1,5 +1,5 @@
  ?xml version=1.0 encoding=iso-8859-1?
 -!-- $Revision: 1.7 $ --
 +!-- $Revision: 1.8 $ --
  refentry id=function.expect-expectl
   refnamediv
refnameexpect_expectl/refname
 @@ -13,15 +13,18 @@
 typemixed/typemethodnameexpect_expectl/methodname

 methodparamtyperesource/typeparameterexpect/parameter/methodparam


 methodparamtypearray/typeparametercases/parameter/methodparam

 -   methodparamtypestring/typeparameter
 role=referencematch/parameter/methodparam
 +   methodparamtypearray/typeparameter
 role=referencematch/parameter/methodparam

 This is just evil. Why don't you add changelog?

--
Michael Spector, Software Developer
Zend Technologies +972-3-6139665 ext.223
ICQ: 7279639
AIM: spektom972
Yahoo: spektom
MSN: [EMAIL PROTECTED]




[PHP-DOC] cvs: phpdoc /en/reference/expect/functions expect-expectl.xml

2006-07-04 Thread Michael Spector
michael Tue Jul  4 14:50:10 2006 UTC

  Modified files:  
/phpdoc/en/reference/expect/functions   expect-expectl.xml 
  Log:
  Add last prototype change into changelog.
  
  
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/expect/functions/expect-expectl.xml?r1=1.8r2=1.9diff_format=u
Index: phpdoc/en/reference/expect/functions/expect-expectl.xml
diff -u phpdoc/en/reference/expect/functions/expect-expectl.xml:1.8 
phpdoc/en/reference/expect/functions/expect-expectl.xml:1.9
--- phpdoc/en/reference/expect/functions/expect-expectl.xml:1.8 Tue Jul  4 
08:26:08 2006
+++ phpdoc/en/reference/expect/functions/expect-expectl.xml Tue Jul  4 
14:50:10 2006
@@ -1,5 +1,5 @@
 ?xml version=1.0 encoding=iso-8859-1?
-!-- $Revision: 1.8 $ --
+!-- $Revision: 1.9 $ --
 refentry id=function.expect-expectl
  refnamediv
   refnameexpect_expectl/refname
@@ -108,6 +108,30 @@
link 
linkend=constants.expect.exp_fullbufferconstantEXP_FULLBUFFER/constant/link
   /para
  /refsect1
+ refsect1 role=changelog
+  reftitle.changelog;
+  para
+   informaltable
+tgroup cols=2
+ thead
+  row
+   entryVersion;/entry
+   entryDescription;/entry
+  /row
+ /thead
+ tbody
+  row
+   entry0.2.1/entry
+   entry
+   Prior to version 0.2.1, in parametermatch/parameter parameter a 
match string was returned,
+   not an array of match substrings.
+   /entry
+  /row
+ /tbody
+/tgroup
+   /informaltable
+  /para
+ /refsect1
  refsect1 role=examples
   reftitle.examples;
   para


[PHP-DOC] #38011 [NEW]: suggest $foo = new Bar(); for PHP4

2006-07-04 Thread joliver at gmx dot at
From: joliver at gmx dot at
Operating system: all
PHP version:  Irrelevant
PHP Bug Type: Documentation problem
Bug description:  suggest $foo = new Bar(); for PHP4

Description:

Please provide an advice to PHP4 users to use
$foo = new Bar(); 
instead of $foo = new Bar(); 

Contrary to the examples in the documentation, in PHP4 
instances of objects should be initialisised with

$foo = new Bar();

because here $foo is a reference to the created instance 
of Bar, while for

$foo = new Bar();

$foo is a copy(!) of the instance.

Appart from performance and memory issues, in the second 
case parameters in the constructors will be copied to, 
because the whole object is copied. That means for 
example, that for:

$foo = new Bar($this) 

$foo is an instance of Bar where $this is not the owner of 
that instance any more, because $foo is a copy of the 
newly created instance.

Good example in german: 
http://www.usegroup.de/software/phptutorial/klassen_und_objekte.html#ref_owner

Reproduce code:
---
?php

class myC1
{
  var
$greeting;
  var  $theC2;
  function sayHello()
  {
  echo $this-greeting;
  }
  function myC1()
  {
  $this-greeting=Howdy;
  $this-theC2=new myC2($this);
  }



}

class myC2
{
  var $owner;
  function myC2($owner)
  {
$this-owner=$owner;
$this-owner-greeting=bah;
  }
  function something()
  {
$this-owner-greeting=hulla;
// This is supposed to change myC1's greeting to hulla, overwriting
bah.
  }
 }


$test=new myC1(); //$test=new myC1();
$test-theC2-something();
$test-sayHello();

?

Expected result:

$test=new myC1();

returns the excepted result in PHP4. Please provide that 
advice for PHP4 users in the documentation.

Actual result:
--
As described above, $test=new myC1(); returns a copy of 
the instance, therefore $this in myC1 gets lost.

An advice for PHP4 users would be helpful, in my opinion 
in PHP4 
$foo=new Bar(); should be used instead of 
$foo=new Bar(;), which is not mentioned anywhere in the 
documentation.

(of course i know in PHP5 this as been fixed because 
objects are passed by reference.)

Thank you!
Oliver

-- 
Edit bug report at http://bugs.php.net/?id=38011edit=1
-- 
Try a CVS snapshot (PHP 4.4): 
http://bugs.php.net/fix.php?id=38011r=trysnapshot44
Try a CVS snapshot (PHP 5.2): 
http://bugs.php.net/fix.php?id=38011r=trysnapshot52
Try a CVS snapshot (PHP 6.0): 
http://bugs.php.net/fix.php?id=38011r=trysnapshot60
Fixed in CVS: http://bugs.php.net/fix.php?id=38011r=fixedcvs
Fixed in release: 
http://bugs.php.net/fix.php?id=38011r=alreadyfixed
Need backtrace:   http://bugs.php.net/fix.php?id=38011r=needtrace
Need Reproduce Script:http://bugs.php.net/fix.php?id=38011r=needscript
Try newer version:http://bugs.php.net/fix.php?id=38011r=oldversion
Not developer issue:  http://bugs.php.net/fix.php?id=38011r=support
Expected behavior:http://bugs.php.net/fix.php?id=38011r=notwrong
Not enough info:  
http://bugs.php.net/fix.php?id=38011r=notenoughinfo
Submitted twice:  
http://bugs.php.net/fix.php?id=38011r=submittedtwice
register_globals: http://bugs.php.net/fix.php?id=38011r=globals
PHP 3 support discontinued:   http://bugs.php.net/fix.php?id=38011r=php3
Daylight Savings: http://bugs.php.net/fix.php?id=38011r=dst
IIS Stability:http://bugs.php.net/fix.php?id=38011r=isapi
Install GNU Sed:  http://bugs.php.net/fix.php?id=38011r=gnused
Floating point limitations:   http://bugs.php.net/fix.php?id=38011r=float
No Zend Extensions:   http://bugs.php.net/fix.php?id=38011r=nozend
MySQL Configuration Error:http://bugs.php.net/fix.php?id=38011r=mysqlcfg