This issue came to hit me this morning when looking up info on class constants. The current PHP documentation located at http://us2.php.net/manual/en/language.oop5.constants.php has code displayed that doesn’t work. Specifically the concept of
$obj = new myObject(); echo $obj::constantName;
This simply doesn’t work in PHP 5.2.4 (and I assume 5.2.5). You get the dreaded “unexpected T_PAAMAYIM_NEKUDOTAYIM” message (well, it’s not ‘dreaded’ but you know what I mean!).
Above the code block that shows that type of code, there’s a reference to PHP 5.3.0 which seems to have nothing to do with the code sample below it. I can only assume that this behaviour will work in PHP 5.3.0.
My issue is not with the language itself (this time!) but how this sort of documentation is handled. Updating public documentation well ahead of a release creates confusion. What would help immensely is to have documentation that was archived to specific versions, such that I could put a /5.2.4 in the URL and make sure I was seeing documentation that matched my version. As it stands now, there’s no consistency. I do appreciate some of the messages in docs that say ‘before version X, foo() behaved like Y’ and similar messages. They let you know that if you’re seeing different behaviour, there’s a reason. With this current class constants page, there’s no indication that the given code samples will break in all current versions of PHP and are (I’m theorizing) intended for a future version.
Maybe I’m missing something very obvious – are there archived versions of the documentation already that I’m just missing?
Other possibility – this works in PHP 5.2.5, but not 5.2.4. Given how major changes in underlying functionality sometimes seem to crop up in minor point releases, this would not surprise me. Is this the case? Am I just WAY behind the times using 5.2.4? There are no references to this behaviour change in the 5.2.5 release notes, so I assume it didn’t change in 5.2.5.
The PHP documentation includes release specific notices and info. It is a huge task to maintain a reliable documentation and needs constant updates.
I know that the PHP doc team is looking for help to either keep the docs updated (like what you describe) or to write missing chapters like what we are adding in 5.3/6.x.
If you feel like you can help, please do, you will be more than welcome.
That is a 5.3 behavior. They’re allowing dynamic static calls with that. Should be noted in the documentation however. You might want to open a bug against the docs to have that fixed.
I think it got time that the PHP manual gets split up into versions for example like the Apache or mySQL manuals.
Pierre, I understand it’s a big job, and I called out that it does happen on an ad-hoc basis already. I was a bit surprised that this has been in the docs since *november* of last year – the docs for this functionality have been wrong for at least 3 months. Ben mentioned the idea of separate versions of docs, which is sort of what I’m suggesting. It would actually make it easier than trying to put loads of “after version X this changed” in the core documentation.
Hrm yeah the Zend framework docs have this problem too!
Including the php ver in the URL or maintaining separate versions could be a maintenance nightmare. As a temporary measure it would be helpful if the code samples in the PHP included a comment along with the code informing the reading of the reqd PHP ver.
For example:
$obj = new myObject();
echo $obj::constantName; // only works in PHP 5.3+
Just a thought
This bug was fixed last month in CVS, as a bug report was submitted and solved. But the manual builds are held up currently, something that is being worked on.
The idea of version specific manuals comes up from time to time, and is a huge topic. I personally hold the view that people should know previous, current, and future behaviours in PHP especially considering how it changes often. We’ve implemented changelogs in functions, and are considering ways to nicely insert them elsewhere too. A comment in the code was the solution here.
But feel free to propose changes to the doc mailing list, and ideally include how to implement/maintain them.
Hey Philip:
1. If you left an audio comment, it didn’t work. Apologies – I’m working out the kinks here.
2. What do you mean by changelogs in functions?
Thanks!
“I personally hold the view that people should know previous, current, and future behaviours in PHP especially considering how it changes often.”
What’s the point of the manual then? Why have one at all. It would be nice to just put, “this behavior was introduced to php 5.3.0″.
Yeah Philip, that was a bit of a stretched statement. Quick – tell me how get_object_vars() behaves in 4.1.1. How about 4.1.2? 4.2.1? If you’re able to remember all that minutia, you’re wasted in development and should play professional poker as a card counter – you’d likely make way more money
The audio comment can safely be deleted. I was clicking random buttons to see what they would do.
An example changelog entry: http://php.net/htmlentities
Mark, not sure what you mean. We do do that.
Hey Philip – thanks for pointing that out – certainly a help. I seem to have noticed it before but wasn’t coming to mind. Having some method of indicating what version the sample code is intended for would be the other piece of the puzzle for me. Alternatively, as I said before, just having separate versions of the docs would be good. I’d *think* that just taking a snapshot on the day a version is release and archiving that, even if only available for download, would help. php_en_manual_5.2.1.tar.gz perhaps?
Thanks
Oh, I understand now… we are miscommunicating. The manual is a reference that stores this information for us, because the manual is an extension of our brains. A reference tool. Having the manual tell us behaviour changes lets us know if said changes affects our code. If we don’t care, then we don’t read it. But if we had a version specific manual, we wouldn’t have that choice.
And I don’t think snapshots would help because bugs do exist (and are fixed) in the docs, and this would require us to never document future features. And even more old manuals would litter the Internet landscape, something that is already a problem.
Yes, there is a changelog for functions, but not for language features…
http://us2.php.net/manual/en/language.oop5.constants.php
This page does not specify anywhere that the example code only works in php 5.3.0. The sentence ” As of PHP 5.3.0, it’s possible to reference the class using a variable.” is ambiguous at best, and wrong at worst.
$a = new ClassA();
$a::constant; //this gives a parse error.
Not that $a is an object, not a string “ClassA”. So I don’t understand that line to mean that you can reference static class constants via an object instance. I read it as, you can dynamically access static class constants if you have the name of the class in a string.
About the manual versions. I don’t think anyone is asking for simply timestamped manuals, but manuals that relate to specific versions. I think the main problem is that php version numbers don’t coordinate with new features very well. Breaking backwards compatibility changes regularly happen in 0.0.X releases, therefore it would be nearly impossible to have coherent manuals for versions of PHP with major changes to function behavior. If a plan was developed to tie version numbers into functional changes, bug fixes, and new features, then I think the manuals could be easily segmented into major/minor releases like Apache and MySQL manuals. ..or even just Major numbers would be pretty helpful.
If PHP4 is really EOL, why do I care how it behaves? It turns 5 features into footnotes and bullet points, when they should be first class citizens.
I think it would be a bad idea to split it up. Currently the docs make effort to note down when a feature was added or changed. This way I can see on a single page how a specific feature will work on all the different PHP versions I have to support
Mark, the example you give is a bug, one that is already fixed in CVS but not online, as explained above. And the timestamped versions idea was a reply to a related comment here.
And the majority of people use older versions of PHP, this is a fact. The manual does its best to reflect current behaviour, but must keep in mind the old too. And also the reality of it is there aren’t enough volunteers to maintain a utopian state. However, concrete ideas are 100% welcome…
Its the time to split up the php manual like mysql
http://www.w3answers.com
Philip – here’s a concrete idea/suggestion.
Right before a new PHP version is released, generate all the documentation as it stands at that point in time. It should all reference the current version as of that day. Archive all of the generated documentation – just the downloadable stuff for now – and label it as a particular version number.
Example:
If PHP 5.2.6 was to be released tomorrow, all the current documentation (which should be for 5.2.5!) would be generated and labelled as 5.2.5 documentation. This would be downloadable for people to grab and use as needed. Then 5.2.6 would be rolled out and documentation for that version would be generated as needed.
This would allow people to grab docs for a specific version and use it locally. They’d know they have the right docs for their version.
I’m not sure I can get more concrete than that, but there it is.
Thanks!
Often the comments of users in PHP online manual are very useful.