Forum Moderators: coopster
So often, you get only a few "examples" in an example file on how to use the code - helpful for learning to use it, but not the kind of information I need before using it. In other cases, there is auto-generated documentation with phpdocumentor, but then it's very sparse. In cases of well-established classes, and a few less-established ones, there's also end-user documentation; however, even then I'm usually left with a lot of questions.
I'm writing this now in the middle of a "real-case" example. I have long strings that need to be parsed, in which parts are caught with regular expressions designating that they need to be specially parsed using BB code, or maybe a subset of the BB code tags. There's a class for doing this in PEAR::HTML. I'd really love to use it. However, I've got to ask myself the following questions, which aren't answered in the phpdocumentor documentation:
- what will the parser do with tags that aren't properly closed? Fail to close them, ignore them, print them out, issue some kind of warning?
- How often can I create a new parser object? How often can I call one of the methods in this class? Is it designed more for a one-off per page view, or is it safe for loops of a hundred iterations, a few thousand iterations long? OK, it's not typical that anyone who writes a script produces benchmarks; but at least it could be indicated: what kind of use / abuse did the script author have in mind when writing it? For what sort of scale was intended? I could install it, set up test cases, benchmark it through x iterations. But then again, for code I write myself, I know what it is going to do / isn't going to do, and have a gut feeling about performance issues - whereas I don't have this until I've scrutinized the PEAR code, which can take longer than writing my own.
First question: would you use PEAR more often if classes were better documented?
Next, addressing the 'bloat' issue. In cases of classes that deal with a complex or difficult protocol, and are are sort of expected to provide the right response for every possibility under the sun that can occur within that protocol, classes are going to be robust and probably a bit slow. However, it's often the case that scripts only require functionality from a more commonly-used subset of a certain protocol. My second question then: would you make more use of PEAR if there were more 'lite' versions of classes, with less 'bloat', but could only deal with a certain subset of common procedures / issues arising from a particular protocol? Where maybe short 'alpha' classes not dealing with every last protocol quirk, but after being tested, could be released as lite versions?
The PEAR project is one you really can't shake a stick at. With the review procedures they have in place, it looks like they're aiming at Debian-like stability and functionality, and little toleration for triviality. If there's bloat, it's becuase the class is supposed to deal with a particular protocol, and that means dotting every i and crossing every t - dealing with everything the protocol can throw at you, and doing everything you're expected to be able to do within a particular protocol. Then you have "bloat", no questions asked, if you're only looking for a few specific features. Fantastic goals, I think. But then we want the lite versions for scripts that need to be doing multiple things at once, but don't need the full nine yards of any specific protocol. And we want the info.
Then I think about feasiblity. PEAR is the only 'official' set of non-native classes in some way endorsed by the PHP group -- they're almost 'sub-native', given you can automatically install any of the stable ones in a php default installation. Maintaining or contributing to a PEAR class should be a status thing - it should be a recognized something that you want to put near the top of your CV or resumé, since it's such a highly elite slice of the billions of lines of PHP code that are out there. The thousands of PHP programmers out there should be jumping at the possibility of contributing to the code or docs of PEAR classes, or of refining classes to make more scalable versions which fit a more limited subset of requirements. At the moment, there are 398 packages, and only 211 maintainters - almost two packages per maintainer (which includes non-lead maintainters).
Anyways, think about the PEAR packages you've turned down because of lack of documentation, or bloat. Could you help provide some documentation or information? Is there a specific subset of features that not only you will need, but also a significant percentage of PHP users who might turn down the class due to its girth? Then please consider contacting your town's local PEAR representative or reporting to [pear.php.net...] . (hypocrisy warning: I haven't yet)
I had been planning on aiming for compatability with PHP installs as old as 4.1, but realized that for one really essential thing this puppy does it needs 4.3, and it would be difficult to loop through checks and modifiers to offer it for 4.1 but with this functionality missing. So I might drop some of the PEAR I had been using too this point: functions in the package PEAR Compat. If you're not familliar with this package, you might want to try it out if you use 4.3 - only functions - it includes files which define functions like file_get_contents() and var_export() for older PHP versions. If you don't want to use the whole class, you can just use the individual files -
if(!function_exists('var_export')) include 'PEAR_partsdir/var_export.php'; . If you offer your code to the outside world, it can make a big portability difference - there are still a lot of servers out there running 4.1 php's.
