glennweb.net

I find that, in general, much of the PHP scripts/class code (this includes Pear code) that developers make available is overly complex, requiring a large time investment to actually make it useful. Which of course actually makes their code generally less useful in real world contexts. Oh Dave, your such a critic. “What should these developers do” you say?

If you have a complex set of scripts/classes/etc. here are the things I would want to help my ‘real world ramp-up time’ with your code:

• A High-Level Diagram: nothing elaborate, but I want to see from a higher level how your code fits in with its surroundings (PHP, databases, directories, servers, etc.). If your documents dump me right in at the branches-on-trees levels it will take me days of dinking with it to see the actual forest, days I spend in frustration (why the heck is this needed here?…, etc.), or not (often the case).
• At least one real world, detailed example: So many scripts/classes/etc. come with the most God awful, trivial, only-uses-one-aspect-of-the-code examples. These are just worthless. Period. Even when they are correct (which very often they aren’t because the code base changes at a 2.5x rate compared to documentation). Just one real example can negate reams of missing documentation, really.
• If the script/class is of a framework-ish or application structure-ish type I would like to have a small (empty) reference implementation to start with. This should be structured using the ‘best practices’ for your code. This will give me something to hang test code on and will get me up to speed in very short order (even if I don’t understand what I’m doing yet). Be sure to take into account other ‘best practices’ when you set this up (normal web server layouts, code references, etc.), and document those that you don’t adhere to.
• And in my dream world, I would like to see actual documentation. That is documentation that has actual text (not just the method/function definitions and their undocumented parameters) describing the inner-workings of your exquisite, hand-crafted code base. Even sprinkle on some working example code snippets.

Interesting that I was just mentioning Paul Jones and his various PHP related efforts, he has just announced a new one centered on PHP5, the Hive. Unfortunately I’m missing the initial PHP5 wave at the moment, waiting on more widespread deployment (hosting services, etc.). However given the quality of Paul’s other efforts and that Hive is the successor to the Yawp/Savant code line I will be watching very closely.

In his Hive announcement Paul stresses comprehensibility, which is definitely a positive trait in his other PHP efforts, and a very worthwhile goal that much of the PHP ’script’ world should aspire to. I’m glad he brings up this point in reference to Pear, as that is mostly what kept me from using Pear code for quite some time. Until you get over the Pear hump, Pear code is difficult to visualize. That is it isn’t apparent what Pear can offer you (or even what actually comprises Pear), what pieces/files you actually need if you think an element you’ve seen might be useful, or how to actually get the elements. Much of this could be remedied (disregarding actual package code complexity) at the Pear web site level, which suffers from a lack of higher-level information or documentation.

These projects have reached the ‘finger hovering over the launch button’ stage (they are live), and both were done with some new-ish PHP backend tool technology (Yawp, DB_Table, Savant2) in conjunction with a Glennweb custom CMS system:

• Nathan Gunn
• UI CRME (Council for Research in Music Education)

All three of these great tools come from Paul Jones, who from the looks of his other projects is quite a busy developer.

Yawp: It’s not a framework but a well thought out class that helps pull together common PHP web development pieces. It is centered around a file-based configuration file which fronts useful tools from Pear and elsewhere. From that configuration file it is easy to setup Error handling, Database Abstraction, Templating systems, Debugging tools, etc.

DB Table: A small footprint Database Abstraction layer which is a Pear project. DB Table encapsulates the table/field definitions and table specific SQL code. It in turn uses the Yawp configured DB (Pear) database connection classes to interface with the database. It can also generate a Pear HTML QuickForms form from the same field definitions, making basic form processing very quick to develop.

Savant2: This is the first of Paul’s projects that I started using. It was an offshoot of some templating code that Brian Lozier had published a couple of years ago, following an article by Harry Fuecks (whew). Before Savant I had cleaned up Brian’s original code and used it in a few projects with great success. Savant takes PHP as Templating language idea quite a bit farther, rolling it into an Object Oriented structure and adding plugins and filters. It makes templating a site and incorporating dynamic site features a very straightforward operation and I have used it on all my recent projects.

I successfully launched the new Champaign City Site last Friday (6/11). The Phase II site redesign features a new look for all the secondary site pages (90+). The site also now features:

• no frames throughout
• a browser-based custom CMS to manage all site content
• a browser-based custom CMS to manage all News, Calendar, and Employment entries
• site-wide, user toggle-able, Text-Only display
• CSS positioning is used for the bulk of the site
• tables used only for tabular data and minor site structure(home, header, footer)

Glennweb.net work on the site included:

• development of the CMS database(MySql)
• development of the browser-based CMS (PHP/MySql)
• development of CSS positioning, layout, and display
• templating of the new site design (PHP, phpTemplates)
• development of the Text-Only site wide feature
• conversion and integration of all content to the new CMS (90+ pages)
• testing and deployment of the final site

The site was designed by John Bonadies.