When 5.3 came around, I literally had to diff the sources to figure
out what was going on, I am not going through that again.
...
If that doesn't happen, we wind up with more features like streams and
filters which took 5+ years to document.

The person making changes to the language needs to ensure those changes
are documented. That can include either writing a first draft of the
docs themselves and/or teaming up with someone on the documentation
team. The most reliable thing to do is commit the php-src and phpdoc
changes in one commit.

At the very least, we could have a TODO file in phpdoc that contains
a simple plain text explanation of the new functionality.

"You can say that I'm a dreamer...",

--Dan

--
T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y
data intensive web and database programming
http://www.AnalysisAndSolutions.com/
4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409

Hi!

The UPGRADING file is also completely worthless.
I have no idea what is going on, as a dev, nor as a documentor.
Be it traits, closures, or whatever random new parameter or function was added.
When 5.3 came around, I literally had to diff the sources to figure
out what was going on, I am not going through that again.

I'll check out UPGRADING file, thanks for reminding about it, however I
do not think UPGRADING is the right place to document language features

• and, frankly, I didn't hear about the rule that one is supposed to
  update UPGRADING file with each change.

I think stuff should be documented first and foremost in the usual place

• in the manual and it is the responsibility of whoever adds the feature
  to ensure that it happens. I'll go through new features that are in TODO
  and make a list of which ones aren't properly documented soon.

Right now, for example, as far as I can see Closure is not documented at
all with regard to which methods it has, and the syntax for anonymous
functions in general is somewhat learn-by-example - neither static
closures nor "use" aren't explicitly documented - even though the docs
mention importing parameters from parent scope, the docs text (as
opposed to the example) never mentions the "use" keyword is used for
that. Neither use by-value/by-reference is mentioned.
The issue of scoping is completely avoided and the only note
tangentially implies you can use $this in the closure but gives no
explanation about how one would actually use it.

It would be great if we could improve this ASAP in the manual.

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

Hi!

Following Hanness' mail a week or so ago, I went over NEWS and the wiki
and here is the list of undocumented stuff we have now in 5.4. It may be
not complete, so if you know of any other undocumented stuff please tell
(and submit docs bug). Here it goes, together with persons responsible
for them (from NEWS or commits) where possible:

CLI webserver - didn't find any mention in the docs

XsltProcessor::setSecurityPrefs($options) and getSecurityPrefs() -
Chergu, Nicolas Gregoire
RegexIterator::getRegex - Joshua Thijssen
ReflectionExtension::isTemporary & isPersistent,
ReflectionClass::isCloneable, class ReflectionZendExtension, - Johannes

OpenSSL functions:
openssl_csr_get_public_key, openssl_csr_get_subject, openssl_decrypt,
openssl_dh_compute_key, openssl_digest, openssl_encrypt - shown in the
manual as undocumented, additionally for encrypt and decrypt signatures
do not match actual state of affairs in 5.4 - options is long, but bool
parameter is listed instead.

mysql_list_dbs - not documented as deprecated in 5.4 - Andrey
mysqli_result - not documented as implementing Traversable - Andrey,
Johannes
ldap_control_paged_result, ldap_control_paged_result_response - pajoye,
scottmac
ldap_parse_reference and ldap_parse_result undocumented too, btw
JSON_BIGINT_AS_STRING constant undocumented - Sara
JsonSerializable interface - listed in manual as undocumented - Sara
Spoofchecker class - constants and methods are not documented - Scott
hex2bin - Scott
import_request_variables, define_syslog_variables,
session_is_registered, session_register, session_unregister - not
documented as removed in 5.4
Ini options allow_call_time_pass_reference, define_syslog_variables,
highlight.bg - not documented as removed in 5.4
class_uses - Stefan
Magic quotes removal in 5.4 not documented - Pierrick, Pierre
Short array notation - Pierre
windows_show_crt_warnings INI directive - Pierre
SORT_NATURAL and SORT_FLAG_CASE options for sort functions - Arpad
disable_post_data_processing - Gustavo
callable type in function args - Hannes
SessionHandler class - Arpad
Closure::bind and Closure::bindTo - Gustavo
but in fact whole Closure class is badly documented

Please chip in and document this stuff - especially if you contributed
in, but if you want to just help and document somebody else's
contribution - I don't think there would be many complaints either :)
I've also put it on the wiki for tracking: https://wiki.php.net/todo/undoc54

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

Hi!

The UPGRADING file is also completely worthless.
I have no idea what is going on, as a dev, nor as a documentor.
Be it traits, closures, or whatever random new parameter or function was added.
When 5.3 came around, I literally had to diff the sources to figure
out what was going on, I am not going through that again.

I've sent a separate email about undocumented stuff but I'm kind of
confused about UPGRADING file - what should be there and how it is
related to NEWS? Should one ad stuff both to NEWS and UPGRADING or I as
RM should add stuff from NEWS to UPGRADING later? Do we have process
described anywhere?

Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227

'

do we have a wiki/documentation about what exactly ended up in 5.4
from the Closure improvements? (Rebind)

https://wiki.php.net/rfc/closures/object-extension#privateprotected_members_scope
is really hard to read, as it contains all of the suggested ideas and
possible solutions, etc.
if not, maybe someone with the required knowledge  could start working
on adding the documentation?

I don't think so, but if I had to summarize the innovations in 5.4, this
would be it:

• Closures can now have an associated scope

• Closures can now have a bound object

• Closures can now be either static or non-static

• Closures defined in a place with an active scope are scoped accordingly

• Closures defined inside an instance method (or bound closure) have a bound
  object (namely $this)

• Closures are static if defined within a static method or with the static
  keyword (static function() { ... })

static => !bound
(but it's false that !static => bound)
bound => scoped
!static && scoped => bound
(i.e., if !static, scoped <=> bound)

The bound instance and the scoped can be freely changed with Closure::bind
and $closure->bindTo, subject to these constraints.

"- Closures can now have an associated scope"
as it is https://wiki.php.net/rfc/closures/object-extension#privateprotected_members_scope
?
at first I thought that scope means Variable scope, but I think I get
it now: it means that when the Closure calls/access something through
$this, it will be handled as it was called/accessed from the given
class(scope).
and this also explains why we had to add the third param for Closure::bind.
the bound param defines what is the $this pointing to, and the scope
means that from what scope would be used for accessing the $this.
having a static Closure means that it won't have the $this, but it can
still have a scope (so it can interact with other static methods).

thanks, I think I managed to wrap my head around that!

--
Ferenc Kovács
@Tyr43l - http://tyrael.hu

Hello !

I don't think so, but if I had to summarize the innovations in 5.4, this would be it:

• Closures can now have an associated scope

• Closures can now have a bound object

• Closures can now be either static or non-static

• Closures defined in a place with an active scope are scoped accordingly

• Closures defined inside an instance method (or bound closure) have a bound object (namely $this)

• Closures are static if defined within a static method or with the static keyword (static function() { ... })

Is it possible to have sample code about these ?
They will be very interesting to understand the RFC correctly and write documentation or tutorial.
For example, i was tryed to use $this in a closure with PHP 5.B beta without any success :/, so if using $this in a closure is possible, i would like to know how to do it..

Best regards,
Fred

========================================================================
Frédéric Hardy : Architecte d'application/Admin. système/Ergonome
CV : http://blog.mageekbox.net/public/cv.frederic.hardy.pdf
Blog : http://blog.mageekbox.net
Twitter : http://twitter.com/mageekguy

Sure, and I mentioned that initially. But we at least need to look at
each failing test and make a determination before blindly pushing out a
beta. I have fixed a couple of easily fixable tests in the past couple
of days that anybody who looked at them could have fixed.

-Rasmus

Unless test failures are critical, it seems worth either commenting out
or converting to xfail ones that can't be immediately fixed.

That gives a 0 fail baseline to work from for detecting regressions, and
test failures should be associated with bug reports anyway so it's not
like they'd get lost forever.

Nat

On Mon, Aug 29, 2011 at 4:39 PM, Rasmus Lerdorf <rasmus@lerdorf.com
mailto:rasmus@lerdorf.com> wrote:

> Hi!
>
> 
>> I would really like to see the number of failed tests hit 0 before we
>> even consider a 5.4 beta release. It shouldn't take that long to
fix the
>> remaining tests. I'm down to 48 with just about everything
enabled on my
>> Ubuntu laptop here. They are listed here if you are curious:
>> http://codepad.org/jtVeWgao
>
> It'd be a great idea to get 0 fails. Could we do it by Wed? ;)

I don't know, but the release schedule relies on us fixing outstanding
issues. Given our recent history, failing bugs are, and should be,
outstanding issues.

-Rasmus