php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Request #60566 Highlight prototype changes
Submitted: 2011-12-19 20:17 UTC Modified: 2013-10-05 09:09 UTC
From: martinb at online dot ie Assigned: krakjoe (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS: Ubuntu 10.04
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: martinb at online dot ie
New email:
PHP Version: OS:

 

 [2011-12-19 20:17 UTC] martinb at online dot ie 
Description:
------------
---
From manual page: http://www.php.net/function.preg-match-all#refsect1-function.preg-match-all-description
---

The fact that the 3rd argument matches was not optional before 5.4.0 needs to be highlighted at the top the documentation, not buried in the change log.



Test script:
---------------
<?php
// PHP 5.3.2
if (preg_match_all('/a/', 'aaa') === false) error_log("returns false");
?>


Expected result:
----------------
Nothing

Actual result:
--------------
PHP Warning:  preg_match_all() expects at least 3 parameters, 2 given in /var/www/noname/test.php on line 3
PHP Stack trace:
PHP   1. {main}() /var/www/noname/test.php:0
PHP   2. preg_match_all() /var/www/noname/test.php:3
returns false

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2011-12-21 14:29 UTC] bjori@php.net 
No, all changes to functions are described as changelog entries

See http://www.php.net/manual/en/about.phpversions.php for more details on which 
versions we document.
 [2011-12-21 14:29 UTC] bjori@php.net
-Status: Open +Status: Bogus
 [2011-12-21 19:16 UTC] martinb at online dot ie 
Did I say they shouldn't? Other changes to functions are highlighted at the top of the document: fgetcsv is a particularly good example. 

Also, is it standard to mark rejected bug reports as "Bogus"? Whether this gotcha (got me anyhow) merits highlighting may be moot but the report is not bogus, and it's pretty objectionable to be so labelled.
 [2011-12-21 21:38 UTC] frozenfire@php.net 
Please don't take the marking of your bug as "bogus" to be an insult. What often 
occurs is that we go through a slew of bugs quickly and weed out the ones we 
won't or cannot fix. Bogus usually means that a submitted bug asks for a solution 
which would be contrary to our documentation style.

In this case, we usually only represent changes to functions in the changelog. 
It's rare that we will make additional mentions of changes, and those are only in 
cases where backwards compatibility is severely effected.
 [2011-12-22 11:09 UTC] martinb at online dot ie 
The backwards compatibility of the *documentation* is affected because it's misleading. This isn't like other cases where a parameter is made optional and defaults to some value, this is a fix to a usage case of preg_match_all (counting instances) where the matches parameter should never have been required and thus it's natural to assume it's always been the case. 

Re "Bogus": words matter. If you don't mean bogus then please relabel the report "Closed" or "Rejected" or something accurate. Failing that please remove it and my email address from your system.
 [2011-12-29 19:42 UTC] martinb at online dot ie 
Hello? Please relabel the report "Closed" or "Rejected" or something accurate. Failing that please remove it and my email address from your system.
 [2011-12-29 19:54 UTC] philip@php.net 
Yeah, the "bogus" label is questionable but it's been here since the 90's. One 
day someone will change it, I reckon, and perhaps that day we'll also change 
"Wont fix" to "Won't fix" although I like that one. :)

I wonder if we could add a little trickery to make the prototype changes clearer, 
in terms of versioning? Maybe a little [note] overlay of some sort, and/or a 
simple indication. Probably only for the phpweb version.

So this bug report is turning into a feature request for something along those 
lines.

But to be clear: This is not asking for version specific PHP manuals.
 [2011-12-29 19:54 UTC] philip@php.net
-Summary: Highlight that 3rd argument $matches only became optional in 5.4.0 +Summary: Highlight prototype changes -Status: Bogus +Status: Open -Type: Documentation Problem +Type: Feature/Change Request
 [2013-10-05 09:09 UTC] krakjoe@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: krakjoe
 [2013-10-05 09:09 UTC] krakjoe@php.net 
The changelog is not buried, it is directly underneath return values, before any examples.

The idea of adding information to the manual concerning version specific prototype changes would not work in the real world, it would clutter and confuse the content of the page. The perfectly visible changelog is enough.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved. 		Last updated: Tue Jun 11 23:01:31 2024 UTC