Re: Standardized way of interpolating variables into PEAR_Exceptionmessages?

On 25/09/06, Alan Langford <jal@ambitonline.com> wrote:

On 2006 09 24 23:15, Greg Beaver wrote: Rather than argue over PEAR_Exception/PEAR_Error/PEAR_ErrorStack, perhaps we could discuss improving the website, and especially the documentation, which is confusing and outdated. Let me be clear though: the work we're all doing on our respective packages is all-important (a la HTML_QuickForm2), I am only suggesting minimally redirecting the energy in this thread to tasks that really need serious attention. I certainly support that! No small part of my confusion here has been reading documentation that says "use ErrorStack, the replacement for Error", then to discover that there's a decent Exception class AND a class for aggregating warnings, and finally -- through this thread -- discover that there's an RFC that supersedes part of what I've read so far. This has led me to do a bunch of work on ErrorStack that has at best peripheral usefulness, and to finally understand a comment Greg made about PEAR_Warning being potentially more useful. I'm willing to put all of this down to learning curve. Compared to a lot of other OSS projects, PEAR's documentation and web site are stellar. But is it frustrating to discover that what you were attempting to achieve is borderline irrelevant (even if the probability of having it ever be accepted was about 0.05 in the first place).

Agreed. I have spent far more time trying to figure out the actual PEAR requirements for error-handling than I have on the core logic of my package proposals. A section in Coding Standards that describes the error-handling requirements and _most importantly_ best practices with copy and paste skeleton examples, differentiated for PHP 4 packages vs. PHP 5 packages, would be a god-send. I have plenty of Docbook-fu, so I would be willing to help mark up the text and add it to peardoc, if the Docbook markup is a barrier. But we do need one or two people to provide the text and code examples in the first place. A structure like the following might be a good start: Error-handling in PHP 4 packages * Issuing errors and warnings with PEAR_Error or PEAR_ErrorStack * Example * Handling errors and warnings thrown by other packages * Example * Defining error codes and messages (global constants and package message array) * Example Error-handling in PHP 5 packages * Issuing exceptions with PEAR_Exception * Example * Issuing warnings with ??? (not sure if there is any recommendation or requirement here) * Example * Handling exceptions thrown by other packages * Example * Defining error codes and messages (class constants and static message array) * Example As I said, it's a start. I think the Coding Standards docs should focus on the core use cases with recommended best practices, and point to the PEAR_Error/ErrorStack/Exception package documentation for advanced possibilities. And as I said, I'm willing to help with the text-to-Docbook part of the job -- but I have to rely on the more seasoned PEAR developers to come up with the actual content. Dan