blogZero

I had such high hopes for Textpattern, I really did. I was sold on the slick looking admin interface, the tons of templates to choose from (or themes or whatever they call them). The nice, clean layout of the Web site. The tons of resources—an almost complete MediaWiki documentation site—plenty of users. Bloody wankers! I was duped!

Cut and Paste?

Oh, at first everything seemed honky-dory. A straightforward install, if a little strange (that's when it started to dawn on me). First, you create a MySQL database, assign a user CREATE, READ, WRITE, etc., privileges. Okay, I've got no problem with that. Next, run the installer. It checks to make sure it can connect to the database, okay, then it spits out this code into a <textarea> and tells you to cut-and-paste the code into a file called config.php. Cut-and-paste? Why not just create the damn file and write the settings to it? That's when the hair on my neck started to crawl. Oh, there would be more, much, much more cutting and pasting to come.

First Post

Okay, I get the sucker up and running. I fiddle with the settings to name my blog and so forth. I fix a few permissions problems on directories, no big deal. I create a quick dummy post, I click "View site" and what does it do? Tries to open another browser window. Ack! But of course I have my browser configured do redirect such nonsense to a new tab. Oh, there will be many more tabs in my future.

The first problem I run into are "friendly URLs." Which I prefer, so do users, so to search engines. Only I'm getting 404 errors. Oh god, here we go, I know what's next. Sure enough, there's an .htaccess file sitting in the root of the install. I cannot stand application packages that blindly assume you have mod_rewrite installed and .htaccess enabled. Which I do, and I don't. The latter for a very good reason that I won't go into here. At any rate, I know what to do, I create a <Directory> container for the package and set the rewrite rules in my Apache config file, then restart the daemon. Viola, friendly URLs! I promptly delete the .htaccess file regardless of "Diagnostics" telling me it's missing.

So off I go to my "View site" tab. The presentation is basic, really basic. But I'm not worried about it, I can choose from one of the hundreds of themes out there or learn how to design one myself, right? I decide to go with the former. I find one, I download the archive. The documentation Wiki tells me to follow the instructions in the archive. Why this isn't standardized is a complete mystery to me.

Zip Files?

Who uses zip files? Folks, I knew Phil Katz. He died a lonely, pathetic alcoholic in a grubby motel room at the ripe old age of 37. Okay, okay, XPInstall files (.xpi) are zipped, JAR files, almost all Unix-like OSs have open-source zip and unzip... Actually, at the time, PKZIP was a pretty revolutionary piece of software, even if Katz stole most of his original code from SEA. At any rate, this was before you could even lay hands on a 56k modem so...

Anyway, I open this archive with my trusty GUI interface for such things and after looking through the contents I find what must be the install instructions since the file is called Instructions.rtf. RTF? How about INSTALL.txt, or how about RTFM? Anyway, I'm reading the "instructions" and they tell me to cut-and-paste the contents of such-and-such a file into such-and-such "folder" (pages, styles, forms). What folders pages, styles, forms? Oh, dear lord, I think, it's time to study the database. Sure enough, CSS, forms and pages are all stored in the database instead of the filesystem. Worse, there seems to be no admin interface to deal with these things. So I open another tab to Google and start searching...and find a plugin called mcw_templates which adds the ability to import and export pages, forms, and stylesheets to/from the database. Why this isn't built-in to the functionality of Textpattern to begin with is a compete mystery to me.

It turns out the "mcw" in the plugin name is the author's initials, so I visit his Web site and promptly discover that he no longer maintains the plugin and it is now on GitHub. The former is a little unnerving, but the latter give me hope. But before I go traipsing off to GitHub I take the time to read over the instructions on installing and using it. Not encouraging: "This plugin is beta in every sense of the word, as it’s only been tested on my 4.03 installation. It might work on other versions, but no promises!" I have the latest Textpattern, v4.0.6, but hey, I'm a masochist so this doesn't stop me. He also states "Regardless of where it’s been tested, this plugin messes around with your database. Do not use it without backing up your database." Oh god, what have I gotten myself into? So I promptly back-up the DB, create the _templates directory and make it world writable, then continue on to GitHub.

Uuencoded plugins?

When I get to the repository I find Mike's blurb on installing the plugin. I read it. It says to "cut-and-paste the following data into the 'Install plugin' box" under admin->plugins. The data looks suspiciously like it's uuencoded to me (actually, it turns out to be base64 encoded which is rife in this package). According to the Wiki, this technique is justified because it "reduces the possibility of errors during transport," or some such nonsense. What transport? You mean between my clipboard and the plugins form? If anything, neophyte user error would be the biggest problem. Okay, so I paste in the data and click the submit button, which is labelled "Upload." What upload? Oh god, my head is starting to pound. At any rate, the data is decoded then you can actually view the source before clicking "Install" to add the plugin. And don't forget, you then have to enable the damn thing by going back to your admin interface, clicking on the Plugins tab, finding it in the list (if you have more than one) and clicking "No" from the Active column. All very intuitive, not!

Speaking of error-prone, does anyone remember the days when PCMag would publish those little debug .COM utilities? I sure do. In order to build them you had to painstakingly type in the data, byte by byte by byte, and then feed it to debug which would spit out the program (written in DOS assembler). Oh god, I haven't thought about that in years. You can even get the damn book from an Amazon reseller for less than a dime (plus $4 shipping of course) if you want. Sigh, I digress.

Okay, so the plugin is now installed. Now what? It turns out the semantics have magically changed and now the plugin (once active) is under the Extensions tab (much fist pounding...) and there it is, has its own tab and everything: "Template Files." Great, now I can back-up the default template and (cough) install the new one. The former works pretty well, I name it "default" (go figure) and head back to my shell to see the results. Sure enough, under the _templates directory is "default" with pages, forms and css folders. Great, I take a look at these to comprehend what's next. It helps some, but this is when things get really ugly. I back up to the _templates directory and create a new folder for the theme that still sits waiting with baited breath over in my archive application. I continue to read the instructions, which go something like "cut-and-paste the contents of this-and-that file into the other file..." Which, like an idiot, I do: 3 stylesheets, 9 forms and 5 pages.

Then, I am told to create a folder for the images used by this theme in the images directory. Which images directory? At the root? Or the txp_img directory in the textpattern folder? I'm hoping that images is the correct place so I upload away. But the instructions aren't complete yet. I have to create two new sections (search and archives). Done. Next, the theme requires two additional plugins. Being an old hat at this already I install away. After several hours, it appears, I'm ready to install the theme. Crossing my sore fingers after this tedious, error-prone process is complete, I go back to the admin interface to the Template Files extension tab. I check the dropdown and sure enough, there is the theme I labored so hard to create, and I import it. What does the plugin do first? Promptly backs up the old template theme once again and names it "preimport-data." Sigh, now I have two copies of the default theme. But what the hell, you can never have enough back-ups, right?

Deprecated tags

So now I head back to my "View blog" tab and refresh. All seems well, until I start getting errors and warning from the engine about "Textpattern Notice: tag is deprecated" and "Article tags cannot be used outside an article context." It turns out "tags," and the pseudo-namespace txp: are Textpattern's method of including dynamic content into your templates. Reminded me way too much of Smarty. The first example, it turned out, was simply a matter of changing the sitename tag to site_name. Only not so simple really, because you have to edit the goddamn source code then reimport the templates back into the database. The second example I never found a fix for because after searching for it all I found were a shitload of sites that Google had indexed with the same exact error message.

All Your Desktop are Belong to Us

When I have a half dozen tabs running in my browser, one for my blog, one for my blog admin, one to the main Textpattern site, one to the documentation Wiki, one to the templates site, one to a forum site, one for GitHub, another for searching Google...you get the idea, there is something terribly wrong. On top of that, a shell window, a text editor window, a GUI zip file archiver app...you need a 40" monitor just to install this damn thing.

Textpattern, I've got one word for you: disappointed.

app> rm -rf tp
app> mysql
mysql> drop database tp

Bye-bye Texpattern.

Okay, now we're getting somewhere! Still dissatisfied at my attempt to reduce the glut in the parent PHP category page, I took yet another look. Wouldn't you know it? There was a definite thread of resources in there relating to improving the performance of applications written in PHP. Not surprising given the growing complexity of the language itself, the applications written in it, and the myriad of Frameworks available these days. The latter is especially critical, because with abstraction, underlying complexity, and growing feature sets, before you even start a project your code base is large. Very large. I'm not going to name names, you know who you are.

Frameworks

I prefer the simple over the complex, the modular over the monolithic. Given the opportunity, I would go with something like CodeIgnitor, which allows you to use the pieces you want and eliminate the rest. The same is true for templating engines. I've used Smarty of course, but it puzzles me why the developers would reinvent the wheel, so to speak, by adding an entirely new dynamic language syntax for templates, when PHP already is a templating language (and a whole lot more). I'm a Savant man, call me an idiot.

Web Publishing

Now we're getting into that gray area I've mentioned before. Is Drupal a framework, a CMS or an application? In my mind, some of each. Wikis and blogware packages I consider applications. It certainly helps to be a developer to get the most out of them, but it isn't strictly necessary.

User or Developer?

And this is also the point where I change my stance on complexity and features. There are certainly faster and easier to use Wiki packages than MediaWiki, but do they have all the power? As always there is a trade-off. I get frustrated with Firefox for instance, because it has become rather bloated and I have bloated it even more with lots of extensions. But as a developer, and a bit of a designer, I could not live without FireBug, Web Developer, ColorZilla, and countless other tools. Christ, I'm not even sure how the hell I managed back in the bad old days of using telnet to test HTTP requests.

Simple vs. Complex

My own philosophy on programming goes like this, start with primitives and build complexity as you move up towards the more abstract and powerful—without going too far. We can see this in the OSI layer model, and an even better example, the early days of Unix. When Dennis Ritchie got tired of working on the kernel in PDP assembler, he took the time to build the more abstract language C. Funny how all the scripting languages, tools, hell, pretty much everything, is written in C, but now days how many of us code in C anymore? Even many of the extensions written for languages like Perl, Python, and of course PHP, are written in C. And there is a damn good reason for this: Performance.

Extensibility

This concept, to me, is absolutely key to good software. Use a high-performance compiled language to build the tools and you're left with solutions that are both easy to apply and responsive. The best of both worlds.

Results

Okay, and now for the final tally. After fragmenting the PHP category into "general" (now around 50 resources) there are six sub-categories (for a total of around 50 also). Divide and conquer my friends.

Specific Navigation

• Part I: Frameworks
• Part II: Wikis
• Part III: Content Management Systems
• Part IV: Debugging
• Part V: Blogware
• Part VI: Performance

Yes, I'm aware that a spider isn't technically a bug, but the cool thing about spiders is they eat bugs. This mechanical spider by Belgian sculptor Stephane Halleux looks especially menacing.

But we're not here to talk about spiders, we're here to talk about software bugs, and more specifically, debugging PHP code. In this fourth installment of the PHP Specificity series I'm going to break from the theme of content management packages momentarily and get into a topic that is not so dear to the programmer's heart. Debugging is a necessary evil and can be painful at times. But the reward, when it happens, is that eureka moment when you find the bug and squash it.

Options

I'm not sure what ever happened to DBG. The author seems to have abandoned the project, or at least stopped updating his Web site several years back. I know the product was rolled into the commercial NuSphere PhpED PHP IDE—whether they took over the code base I'm not really sure. Another option is, or rather was, the PECL package APD by George Schlossnagle (of APC fame). But again, it seems to be dead in the water (the last update was in 2004).

Xdebug

Fortunately we have Xdebug, by Derick Rethans. It has all the features you'd expect from an advanced debugger, and a built-in profiler to help you tackle performance issues. With output in Cachegrind format, once you're done running the profiler on your code, you can fire up your favorite viewer to analyze the results.

If you are an IDE fan, you might want to try the Eclipse PDT, which supports both Xdebug and the Zend Debugger. Or, if you're old-school like me and a Vim user, you can configure the editor to use Xdebug with the DBGp plugin.

Specific Navigation

• Part I: Frameworks
• Part II: Wikis
• Part III: Content Management Systems
• Part IV: Debugging
• Part V: Blogware
• Part VI: Performance

Valgrind is a entire suite of open-source tools, including basic debugging, profiling, and more advanced techniques such as threading, memory management, and leak detection. For the purposes of this article, I will focus on Cachegrind, and in particular within the domain of Web applications. Although there are a number of developers contributing to Valgrind, Julian Seward is the original designer and author.

Out of the three server-side languages I am most familiar with, PHP seems to be the one that is best represented, with some Python—but I found very little if any information on Perl.

What is Cachegrind?

Cachegrind is an Intel CPU emulator and cache profiler that performs detailed simulations of the onboard I1, D1 and L2 caches and can accurately pinpoint the sources of cache misses in your code. It identifies the number of cache misses, memory references, and instructions executed for each line of source code. (paraphrased)

Xdebug

Xdebug is the tool of choice for PHP developers when it comes to standard debugging, and the built-in profiler with Cachegrind output is also maturing. Typically the output is in a file named cachegrind.out.pid, which is plain text, but be careful with large, complex applications as it can grow to on the order of 500MB. The raw data is almost useless, to really analyze and visualize the results you need a parsing/graphing tool. There are several available depending on your platform and needs.

Viewers

Once you have your output you need an application to make sense of it. Listed below are solutions for Linux (or any Unix-like OS running KDE), Mac OS X, Windows, and even a browser-based solution from Google Code.

• KCachegrind
• MacCallGrind
• WinCacheGrind
• Webgrind

Related Reading

• Debugging Questions and Xdebug Answers
• Cachegrind-less profiling with Xdebug 2.0
• Understanding PHP code better with Xdebug
• How to cachegrind a tested Drupal
• CherryPy: Cachegrind
• Debugging PHP
• Spectator
• Useful in-browser development tools for PHP
• FirePHP

Joe Hewitt may be a lesser known member of the original three Firefox cast, but among DOM and JavaScript developers, his work is legendary. In a later Power Tools installment, I will cover in more detail the DOM Inspector, for which he is perhaps better known. At least until recently. This article focuses on FireBug, which Joe has been working on continuously of late (among other endeavors) and what he ultimately considers to be a DOM Inspector replacement.

The latest version of FireBug was released September 12th, 2008.

What in the hell is a FireBug?

I won't get into entomology—which ironically in Greek means "that which is cut in pieces"—although there really is such a thing as a firebug. The extension, on the other hand, is designed to make the Web developer's job a whole lot more productive. With it you can inspect and debug your markup, stylesheets, JavaScript, and even keep an eye on asynchronous XHR object calls back to your server.

Unlike the DOM Inspector, FireBug normally runs in a horizontal console (although you can open it in a separate browser window) underneath the document's rendered view. A statusbar icon indicates if there are any problems with the current page, which can indicate any number of conditions including errors, warnings and results from:

• JavaScript
• CSS
• XML
• XMLHttpRequest (aka XHR or Ajax)
• Chrome

and even problems encountered from remote domains—which can be the source of massive numbers of errors (I'll leave it to Joe to name names). Thankfully you can suppress these messages, or disable FireBug entirely for certain domains, through the options menu.

Almost every object in the FireBug interface is actually a hyperlink. Elements in the source view can be expanded or collapsed and your current XPath is displayed as you explore the document structure. Like the browser itself, views are toggled through a tabbed interface, which include Console, HTML, CSS, Script, DOM, and Net. Each tab has one or more sub-functions associated with that feature.

By using FireBug, you will quickly learn just how much is going on behind the scenes of even the simplest Web page.

Power Tools

• console.log()

Forget about using alert() to test or debug your scripts. By adding console object logging to your code you can pinpoint exactly what is going on, and even restrict messages according to different levels of severity including: informative, debug, warnings, or errors.

The console object also allows you to make assertions to more deeply test your code as well as performing stack traces, time sections of code, and log the number of times a function is called and has been executed.

All of the console logging methods can format strings using patterns similar to the C stdio printf() family of functions.

Command Line Functions

For command line junkies like me, console mode gives you access to a wealth of query and history/editing features you're probably already familiar with. Even more powerful are the following predefined shorthand functions:

• $("id") - A shortcut for document.getElementById().
• $$("css") - Returns an array of elements that match a CSS selector.
• $x("xpath") - Returns an array of elements that match an XPath selector.
• $0 - Variable containing the most recently inspected object.
• $1 - Variable containing the next most recently inspected object.
• $n(N) - Returns the Nth most recently inspected object.
• inspect(object) - Displays an object in the DOM Inspector.
• dir(object) - Returns an array of property/method names on an object (Python anyone?)
• clear() - Clears the console.

>>> inspect(document)

is a good place to get started.

CSS Quick Search

While in Inspect mode, you can use the quick search box to locate any element by entering a CSS selector. FireBug will display all matching elements in the console view, which you can then expand to view more details or switch tabs to explore the stylesheet that defines the rules for each element, the computed propeties and layout/display attributes, JavaScript events that are attached to the element, and even the gory details of DOM for the selected item.

You can also use quick search to match JavaScript events.

In the future, Joe plans on adding XPath search as well as plain text. For those in a hurry, you can try the getElementsBySelector() JavaScript function, which uses the Firefox XPath API to translate CSS selectors to XPath making them a lot faster than searching the DOM directly.

FireBug 1.2

Some of this material is a bit dated. For the latest on FireBug, visit the new Get FireBug Web site and in particular the "Learn more" feature links on the home page and the documentation section.