Re: [PHP-DOC] oop5 basic rewrite informal RFC
Philip Olson wrote: Comments, criticisms, and feedback greatly appreciated! Sounds reasonable, and the more information the better :) And while doing this, it's probably worth thinking about how to ensure oop5 is a first class citizen. Meaning, a person reads about OOP in terms of PHP 5 and those who care can find a section that's specific to how PHP 4 differs. Maybe people have ideas for how best to accomplish this. Regards, Philip Hi Philip, This makes me wonder how close we are to the time when the PHP 4 object reference can be relegated to the Appendices. I mean, even I still have a couple of PHP 4 apps floating around out there so I of course recognize that the ref is still needed, but I agree 100% that the newer object model should have the more readily available documentation. The PHP 4 class/object ref probably also needs a look but honestly at this point I'm not sure it's worth a whole lot of work anymore--newcomers to PHP really shouldn't be using it. Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
On Sep 8, 2009, at 2:00 AM, Lars Torben Wilson wrote: Philip Olson wrote: Comments, criticisms, and feedback greatly appreciated! Sounds reasonable, and the more information the better :) And while doing this, it's probably worth thinking about how to ensure oop5 is a first class citizen. Meaning, a person reads about OOP in terms of PHP 5 and those who care can find a section that's specific to how PHP 4 differs. Maybe people have ideas for how best to accomplish this. Regards, Philip Hi Philip, This makes me wonder how close we are to the time when the PHP 4 object reference can be relegated to the Appendices. I mean, even I still have a couple of PHP 4 apps floating around out there so I of course recognize that the ref is still needed, but I agree 100% that the newer object model should have the more readily available documentation. The PHP 4 class/object ref probably also needs a look but honestly at this point I'm not sure it's worth a whole lot of work anymore-- newcomers to PHP really shouldn't be using it. Torben Torben, I don't share your desire to keep the PHP object reference around for any reason. Appendix, perhaps, but certainly not in the main manual. It was over a year ago that we dropped official PHP 4 support, and over five years since PHP 5.0.0 was released. While I realize that a good number of software packages still support PHP 4 (Wordpress and Drupal, to name the big ones), we no longer do, and I think we only encourage them to drag their feet by maintaining pseudo-support for PHP 4. I would therefore suggest the following: * The drafting of a new section of the PHP 5 OOP manual, listing the differences between PHP 4 and PHP 5 in brief. * The relocation of the PHP 4 section to the appendix. * The application of a large red warning box on each PHP 4 page, stating that this version of the language is out of date and the techniques listed on this particular page may break in future versions of PHP. Best, Brandon
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Torben, This is good stuff. I have the following suggestions: 1. I would add links to the basic.xml page in the paragraph where you state A class may contain its own variables, constants, and functions. I'd link to the sections on properties, constants and methods. 2. I would also add in parenthesis after you describe variables and functions the words property and method, to make clear that classes have properties and methods, not variables and functions (even though the syntax is the same). These, of course, are style suggestions, and not problems with your documentation. I think the work you've done is great, and +1 from me on committing the changes. Best, Brandon On Mon, Sep 7, 2009 at 2:30 PM, Lars Torben Wilson larstor...@gmail.comwrote: Brandon Savage wrote: On Sep 7, 2009, at 3:47 AM, Lars Torben Wilson wrote: Hi all, While going through some bug reports I realized that the 'The Basics' section of the PHP 5 classes and objects section, as it stands, could use some attention. I've been going over it and and have rewritten much of it to be more precise, and have also separated the class variables sect2 out into its own sect1 and given it a bit of a rewrite as well. In days of old I would have just committed this and been done with it, but since I've only recently been getting back into the documentation after having been away for a few years, I wanted to see if there are any objections to such an endeavour. :) For the most part the changes are to make the basics section a little more reference-like and to provide a bit more specificity. I realize that there is still work to be done, but this is, to me, a good first step toward providing a true reference on PHP 5 class/object behaviour. I do realize that there is now some redundant content between the new 'Class variables' sections and the existing 'Visibility' section, but this can either be A) fixed, or B) thought of as a Good Thing since it merely reinforces some important information. The new changes are available at the following URL if anybody cares to take a look and comment on the idea: http://www.thebuttlesschaps.com/phpdoc/language.oop5.html Comments, criticisms, and feedback greatly appreciated! Regards, Torben Torben, To me this sounds like a great idea. Would it be possible for you to post up the diffs? I just want to see what changed, and I'm not very good at reading line for line. ;-) I can take them as a zip file if you like. Thanks! Brandon But of course! Where are my manners? ;) I've attached a tarball containing the diffs to language/oop5/basic.xml and language/oop5.xml and the new language/oop5/variables.xml. Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Brandon Savage wrote: Torben, This is good stuff. I have the following suggestions: 1. I would add links to the basic.xml page in the paragraph where you state A class may contain its own variables, constants, and functions. I'd link to the sections on properties, constants and methods. Sounds good; I agree. There's not a methods section of its own yet, however. I'll take a look at that too. 2. I would also add in parenthesis after you describe variables and functions the words property and method, to make clear that classes have properties and methods, not variables and functions (even though the syntax is the same). I do intend to put this in but just haven't made myself happy with the wording yet. In an earlier draft I had words to this effect, but it just got to be unwieldy, since it felt like if I explained that some people call class variables properties, I should explain that others call them members or member variables or attributes or what-have-you. I'll work on it more. :) These, of course, are style suggestions, and not problems with your documentation. I think the work you've done is great, and +1 from me on committing the changes. Best, Brandon Thanks for the notes (and the kind words). Cheers, Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
On Sep 8, 2009, at 5:08 PM, Lars Torben Wilson wrote: Brandon Savage wrote: On Sep 8, 2009, at 2:00 AM, Lars Torben Wilson wrote: Philip Olson wrote: Comments, criticisms, and feedback greatly appreciated! Sounds reasonable, and the more information the better :) And while doing this, it's probably worth thinking about how to ensure oop5 is a first class citizen. Meaning, a person reads about OOP in terms of PHP 5 and those who care can find a section that's specific to how PHP 4 differs. Maybe people have ideas for how best to accomplish this. Regards, Philip Hi Philip, This makes me wonder how close we are to the time when the PHP 4 object reference can be relegated to the Appendices. I mean, even I still have a couple of PHP 4 apps floating around out there so I of course recognize that the ref is still needed, but I agree 100% that the newer object model should have the more readily available documentation. The PHP 4 class/object ref probably also needs a look but honestly at this point I'm not sure it's worth a whole lot of work anymore-- newcomers to PHP really shouldn't be using it. Torben Torben, I don't share your desire to keep the PHP object reference around for any reason. Appendix, perhaps, but certainly not in the main manual. Hi Brandon, I think I worded my message poorly--I was trying to say that I think the PHP 4 stuff should definitely be relegated to the Appendices. Still available, but not in the main manual. I would therefore suggest the following: * The drafting of a new section of the PHP 5 OOP manual, listing the differences between PHP 4 and PHP 5 in brief. * The relocation of the PHP 4 section to the appendix. * The application of a large red warning box on each PHP 4 page, stating that this version of the language is out of date and the techniques listed on this particular page may break in future versions of PHP. +1 on all counts from me. Best, Brandon Regards, Torben I'll see what I can do to submit a patch tonight containing new language for a Differences Between PHP 4 and PHP 5 section. This is outlined to some degree in the Migrating documentation, but I still think it's a good idea. Does anyone know what we have to do in order to move the PHP 4 documentation into the Appendix without sparking a riot? Brandon
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Brandon Savage wrote: On Sep 8, 2009, at 2:00 AM, Lars Torben Wilson wrote: Philip Olson wrote: Comments, criticisms, and feedback greatly appreciated! Sounds reasonable, and the more information the better :) And while doing this, it's probably worth thinking about how to ensure oop5 is a first class citizen. Meaning, a person reads about OOP in terms of PHP 5 and those who care can find a section that's specific to how PHP 4 differs. Maybe people have ideas for how best to accomplish this. Regards, Philip Hi Philip, This makes me wonder how close we are to the time when the PHP 4 object reference can be relegated to the Appendices. I mean, even I still have a couple of PHP 4 apps floating around out there so I of course recognize that the ref is still needed, but I agree 100% that the newer object model should have the more readily available documentation. The PHP 4 class/object ref probably also needs a look but honestly at this point I'm not sure it's worth a whole lot of work anymore--newcomers to PHP really shouldn't be using it. Torben Torben, I don't share your desire to keep the PHP object reference around for any reason. Appendix, perhaps, but certainly not in the main manual. Hi Brandon, I think I worded my message poorly--I was trying to say that I think the PHP 4 stuff should definitely be relegated to the Appendices. Still available, but not in the main manual. I would therefore suggest the following: * The drafting of a new section of the PHP 5 OOP manual, listing the differences between PHP 4 and PHP 5 in brief. * The relocation of the PHP 4 section to the appendix. * The application of a large red warning box on each PHP 4 page, stating that this version of the language is out of date and the techniques listed on this particular page may break in future versions of PHP. +1 on all counts from me. Best, Brandon Regards, Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
I'll see what I can do to submit a patch tonight containing new language for a Differences Between PHP 4 and PHP 5 section. This is outlined to some degree in the Migrating documentation, but I still think it's a good idea. Does anyone know what we have to do in order to move the PHP 4 documentation into the Appendix without sparking a riot? Brandon I got that done faster than I thought I would. It's not overly technical, but does point out many of the major changes between the two versions. Comments appreciated. oop5.xml.diff Description: Binary data
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Hi Lars: In an earlier draft I had words to this effect, but it just got to be unwieldy, since it felt like if I explained that some people call class variables properties, I should explain that others call them members or member variables or attributes or what-have-you. I'll work on it more. :) When re-writing the Overloading section, it seemed members was the predominant word used already in the docs. It will be good to use a clear and consistent term througout the documentation. Considering the existing usage and the fact that variables already has a separate meaning for something else, I hope you'll consider using the word members here instead of variables. Then explain that there are many other things people call them (and that they particularly hate being called late for dinner). Thanks, --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
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Hi Brandon: Nice stuff. Two qualms with the following: PHP 5's object model also significantly changes the way objects are passed, passing a pointer to the object rather than copying the object. First, passed is the followed immediately by passing. Pick a different word for one or the other. Second, the documentation in general talks about it being by reference rather than as a pointer. Thanks, --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
Re: [PHP-DOC] oop5 basic rewrite informal RFC
On Sep 8, 2009, at 6:12 PM, Daniel Convissor wrote: Hi Brandon: Nice stuff. Two qualms with the following: PHP 5's object model also significantly changes the way objects are passed, passing a pointer to the object rather than copying the object. First, passed is the followed immediately by passing. Pick a different word for one or the other. Second, the documentation in general talks about it being by reference rather than as a pointer. Thanks, --Dan Hi Dan, I have no trouble changing the wording on your first point, as it does make the wording seem a bit odd. However, each spot where the documentation states that objects are passed by reference is wrong. See this blog post by Sara Golemon: http://blog.libssh2.org/index.php?/archives/51-Youre-being-lied-to..html Essentially, objects are like references, pointing to a particular spot in memory where the object can be found. While it's easier to describe objects as being passed by reference in PHP 5, this is in fact not the case. I'm not sure how to change the documentation to reflect this. How specific should we get in the documentation? Best, Brandon
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Daniel Convissor wrote: Hi Lars: In an earlier draft I had words to this effect, but it just got to be unwieldy, since it felt like if I explained that some people call class variables properties, I should explain that others call them members or member variables or attributes or what-have-you. I'll work on it more. :) When re-writing the Overloading section, it seemed members was the predominant word used already in the docs. It will be good to use a clear and consistent term througout the documentation. Considering the existing usage and the fact that variables already has a separate meaning for something else, I hope you'll consider using the word members here instead of variables. Then explain that there are many other things people call them (and that they particularly hate being called late for dinner). Thanks, --Dan :) Yes, this was along the lines of what I was planning to do. I haven't done a statistical analysis, but (as you noted) it seems to me that the preference already in the docs is to use 'member' as opposed to, say, 'property' or 'attribute'. I'll dig into some changes when I get home from work. Cheers, Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Lars Torben Wilson wrote: Daniel Convissor wrote: Hi Lars: In an earlier draft I had words to this effect, but it just got to be unwieldy, since it felt like if I explained that some people call class variables properties, I should explain that others call them members or member variables or attributes or what-have-you. I'll work on it more. :) When re-writing the Overloading section, it seemed members was the predominant word used already in the docs. It will be good to use a clear and consistent term througout the documentation. Considering the existing usage and the fact that variables already has a separate meaning for something else, I hope you'll consider using the word members here instead of variables. Then explain that there are many other things people call them (and that they particularly hate being called late for dinner). Thanks, --Dan :) Yes, this was along the lines of what I was planning to do. I haven't done a statistical analysis, but (as you noted) it seems to me that the preference already in the docs is to use 'member' as opposed to, say, 'property' or 'attribute'. I'll dig into some changes when I get home from work. Cheers, Torben OK, I know I'm following up my own post, but I just wanted to put this out there: on the drive home, I realized what was bugging me about the use of the term member in this context: in typical OOP terminology, a method is also a member, as is a class constant. So while using the term member here might make things more consistent with some existing PHP documentation, my feeling is that the docs would overall be better served by fixing the existing usages to be more in line with common OOP terminology. Personally I like property (as opposed to, say, attribute or field) but it's not a super-strong preference. However, while variable certainly isn't anything to carry forward, I don't feel comfortable using member either. Sorry about that--it just offends my sense of pedantry. ;) Anybody have any thoughts on this? I have no problem with updating the rest of the oop5 docs to match, no matter the outcome of our discussion. Regards, Torben
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Brandon Savage wrote: On Sep 8, 2009, at 6:12 PM, Daniel Convissor wrote: Hi Brandon: Nice stuff. Two qualms with the following: PHP 5's object model also significantly changes the way objects are passed, passing a pointer to the object rather than copying the object. First, passed is the followed immediately by passing. Pick a different word for one or the other. Second, the documentation in general talks about it being by reference rather than as a pointer. Thanks, --Dan Hi Dan, I have no trouble changing the wording on your first point, as it does make the wording seem a bit odd. However, each spot where the documentation states that objects are passed by reference is wrong. See this blog post by Sara Golemon: http://blog.libssh2.org/index.php?/archives/51-Youre-being-lied-to..html Essentially, objects are like references, pointing to a particular spot in memory where the object can be found. While it's easier to describe objects as being passed by reference in PHP 5, this is in fact not the case. I'm not sure how to change the documentation to reflect this. How specific should we get in the documentation? Hi, Don't use pointer, that's also inaccurate, and will be confusing to someone from a C background. Instead, use language somewhat similar to: PHP 5's object model was designed to make it simpler and faster to pass objects as parameters to functions and methods. Rather than copying the contents of the object, PHP 5 represents objects with a handle that is used to look up the actual object contents. The technical details are not important in most situations. The most important thing to understand is that the common PHP 4 practice of using references to instantiate and pass objects should not be used in PHP 5, for both the subtle bugs the practice can introduce and for performance reasons. Greg
Re: [PHP-DOC] oop5 basic rewrite informal RFC
Greg Beaver wrote: Brandon Savage wrote: On Sep 8, 2009, at 6:12 PM, Daniel Convissor wrote: Hi Brandon: Nice stuff. Two qualms with the following: PHP 5's object model also significantly changes the way objects are passed, passing a pointer to the object rather than copying the object. First, passed is the followed immediately by passing. Pick a different word for one or the other. Second, the documentation in general talks about it being by reference rather than as a pointer. Thanks, --Dan Hi Dan, I have no trouble changing the wording on your first point, as it does make the wording seem a bit odd. However, each spot where the documentation states that objects are passed by reference is wrong. See this blog post by Sara Golemon: http://blog.libssh2.org/index.php?/archives/51-Youre-being-lied-to..html Essentially, objects are like references, pointing to a particular spot in memory where the object can be found. While it's easier to describe objects as being passed by reference in PHP 5, this is in fact not the case. I'm not sure how to change the documentation to reflect this. How specific should we get in the documentation? Hi, Don't use pointer, that's also inaccurate, and will be confusing to someone from a C background. Instead, use language somewhat similar to: PHP 5's object model was designed to make it simpler and faster to pass objects as parameters to functions and methods. Rather than copying the contents of the object, PHP 5 represents objects with a handle that is used to look up the actual object contents. The technical details are not important in most situations. The most important thing to understand is that the common PHP 4 practice of using references to instantiate and pass objects should not be used in PHP 5, for both the subtle bugs the practice can introduce and for performance reasons. Greg I have to agree with Greg--although I think that somewhere in the manual it would be good to have an explanation of what's really going on (perhaps in the Appendix). Sara's blog post doesn't deal specifically with passing objects, but assigning them--which is more of a copy-on-write reference setup than anything like a real pointer. Otherwise I think it's good. I would also suggest adding in links to the documentation on cloning, abstract, interfaces, etc. Regards, Torben
