Display log messages from PHP in the browser console in Safari and Firefox (with firebug). You no longer have to use print_r statements from PHP to figure out what is going on in the code. Besides, print_r statements  mess up the DOM and HTML layout.

Features

• Log debug messages directly from themes and plugins.
• Display log messages in the browser console, without muddying up the browser display.
• Displays complex structures such as arrays and objects in pretty print.
• Shows the line number and file from where the message was logged ( you won’t lose track of log statements ).

Screenshots

Firefox console showing debug messages.

Safari console showing debug messages

Installation

1. Verify that you have PHP5, which is required for this plugin.
2. Download the whole wplogger folder into the /wp-content/plugins/ directory.
3. Activate the plugin through the Plugins menu in WordPress.

Requirements

• Make sure that your theme template has a footer ( index.php should have a get_footer() function call at the end).
• Turn on the console in your browser:
  • Firefox: The Firebug extension needs to be installed and activated.
  • Safari: Show the Error Console from the Debug/Develop menu.
    Details on how to enable the Debug menu for Safari on OSX and Windows.

Usage

After activating the plugin, the following PHP function call can log any PHP expression to the console log.

$wplogger->log( php_expression [, message_type] );

Use cases

Logging from template files

This is from inside the loop to display post IDs.

<?php $wplogger->log( 'Post ID: '.$post->ID ); ?>

Output:

[Information: from line 20 in file index.php] Post ID: 125
[Information: from line 20 in file index.php] Post ID: 116
[Information: from line 20 in file index.php] Post ID: 65

Logging from PHP files

This is from  functions.php ( always a good idea to check if $wplogger is available ). Note the message type set to warning through the second parameter.

if ($wplogger) $wplogger->log( get_option('active_plugins'), WPLOG_WARNING );

Output:

[Warning: from line 55 in file functions.<span>php</span>] array (
	  0 => 'wplogger/wplogger.php',
	  1 => '12seconds-widget/12seconds-widget.php',
	  2 => 'get-the-image/get-the-image.php',
)

Logging from plugins

This is from inside a plugin function. Note the global statement to get $wplogger into current scope.

global $wplogger; $wplogger->log( 'No images attached to this post', WPLOG_ERR );

Output:

[Error: from line 206 in file get-the-image.php] No images attached to this post

Credits

Code that forces the wplogger plugin to load first was adapted from the WordPress FirePHP plugin developed by Ivan Weiller.

This plugin is based on PEAR Log, the logging framework that is part of the PHP PEAR library. Current maintainers Jon Parise, Jan Schneider, and Chuck Hagenbuch. PEAR Log is based on code first developed for the Horde 1.3 framework – original authors Chuck Hagenbuch, and Jon Parise.

Download Plugin

Feature requests and critiques

This is the first iteration of the wplogger plugin. Please comment on how you would like to see it improved.

The widget itself is essentially a video player. It uses the widget embed code (need to login) provided by 12seconds.tv. The plugin saves you the hassle of copying and pasting embed code and editing templates.

Installation

1. Verify that you have PHP5, which is required for this plugin.
2. Download the whole 12seconds-widget folder into the /wp-content/plugins/ directory.
3. Activate the plugin through the ‘Plugins’ menu in WordPress.

Usage

The plugin can be used in two ways:

1. Display the widget in the sidebar
2. Embed the widget on posts and pages.

1, Displaying the widget on a sidebar

After activating the 12seconds-widget plugin, go to the widgets section. Now drag the widget into your chosen sidebar and configure.  You must enter a 12seconds username. You can choose to display a skinny (175×290) or fat (380×440) version of the widget. Make sure you click the ‘Done’ button and the ‘Save Changes’ button after making changes.

If you don’t want a widget title just leave the Title field blank.

2, Displaying the widget on a post or page

Using the shortcodes system in WordPress 2.5 and up, the plugin will allow you to embed the widget into your pages and posts.

Use the “12suser” shortcode to display updates for an individual user

• The username attribute is required and is the login/user name to the 12seconds site.
• The *size* attribute is optional and can be “fat” or “skinny” (default).

Use the “12svideo” shortcode to display a single video

• The id attribute is required.
• The id is the last set of digits of the URL when viewing a video on the 12seconds.tv site. The URLs takes the form http://12seconds.tv/channel/username/123456 . The id in this case would be "123456".

PS: The 12s shortcode introduced in version 0.2 will still work, but it has been deprecated.

Styling Guidelines

The widget embed code tag is assigned CSS class twelve-s-widget.

The caption for individual videos ( when you use the 12svideo shortcode ) is assinged CSS class twelve-s-caption to the tag.

<span class="twelve-s-caption">
 ........... </span>

Examples

The following examples show the status updates and individual videos by the 12seconds team.

Skinny widget showing the updates for username ”12seconds”.

Fat widget showing iJustine’s updates (she’s not a regular 12er, but the few she did are masterpieces).

Single video showing 12seconds co-founder Sol Lipman explaining what its all about.

Download the plugin

So, why did I end up writing a WordPress plugin? It all began with choosing a theme ….

Choosing a magazine style theme

I wanted to use a magazine style theme for this blog. I use K2 for all my other WordPress blogs and have been quite happy with it. However, the visual dazzle of recent magazine style themes left K2 a little wanting. Besides, most of K2s unique features like widget control were now standard in WordPress. I was impressed by the Hamasaki theme, developed by Nurudin Jauhari, on Aral Balkan’s blog. However, the elements were a little too large for my taste and the prominent place given to the most recent post was not to my liking. In contrast, Jauhari had another magazine style theme called hijiriah (demo) that I took a liking to instantly.

There are some excellent features in this theme. The money features for me were:

• Built-in ad support ( a nice way to link to my other resources ).
• Dynamic hierarchical navigation menu based on categories ( structured  access to eclectic subject matter ).
• Auto generated image for each post ( pain free way to add some visual interest to the blog page ).

Auto generating an image for each post

I must say that this is the singular feature that really sold me on this theme. Images are generated automatically using a custom version of the Get the Image plugin developed by Justin Tadlock. This plugin is like a cascading image seeker. It also degrades gracefully. The following image seeking sequence is from the plugin README file.

1. Looks for an image by custom field.
2. If no image is found, it grabs an image attached to your post.
3. If no image is attached, it can extract an image from your post content.
4. If no image is found at this point, it will default to an image you set.

The Get the Image plugin has a function called get-the-image that returns the image element ( img tag ) for the auto generated image. A feature that is lacking is flexible image sizing ( you can only choose from predetermined sizes ).  To scale the image to a custom size, the hijriah theme uses an image resizing script called timthumb. This is the whole reason for customizing/hacking the plugin.

The custom version of Get the Image that shipped with hijriah was based on version 0.3. The customization was a simple hack to add an additional function to the plugin called get-the-link that returned the URL of the chosen image for the post ( as opposed to the whole image element ). For some reason, a similar function that existed in Get the Image was now deprecated (probably due to a very good reason unknown to me). The URL to the image chosen by the hacked Get the Image plugin was passed to the timthumb script for resizing and eventually displayed on the blog page.

Another issue was that version 0.3 of  Get the Image had a bug that prevented it from returning an image specified by a custom thumbnail field. Version 0.3.1 fixed this issue.

Upgrading plugins broke image auto generation

Of course, upgrading the Get the Image plugin to 0.3.1 overwrote the hacked version and the hijriah theme was left without an implementation for the template tag get-the-link.

Modifying the code in the hijriah theme ( I was using a child theme ) to substitute get-the-link tag with the get_the_image tag seemed a little too complicated due to the resizing issue. The other option was to write a new plugin that implemented the get-the-link function.

This was a beginning of my sojourn into plugin development…

Writing a plugin to implement the get-the-link template tag

Template tags are used within WordPress theme templates to display information dynamically. It is really nothing more than a call to a function internal to WordPress or externally implemented in a plugin or functions.php file. In the case of the hijriah theme, the get-the-link tag is required in the index.php template file.

The purpose of the new plugin clear and simple. Implement the get-the-link function by calling the get_the_image function in the  Get the Image plugin. I just have to use regex to extract the src attribute from the image element and return it. Simple right? Well, there were a few important things that I had to learn first.

Important stuff about plugins

This is my first attempt at writing a plugin for WordPress. I had to dispel some preconceived ideas.

It’s been awhile since I did any coding in PHP. Coming from my recent ActionScript 3 background and dabbling extensively in OOP and design patterns I thought the new plugin could simply extend the  Get the Image plugin class and override a method or two. But, noooo! I quickly realized what I was up against as my PHP started to come back.

WordPress has a nice modular architecture, but it is not modular in the OOP sense. Here is the definition of a plugin from the WordPress Codex.

A WordPress Plugin is a program, or a set of one or more functions, written in the PHP scripting language, that adds a specific set of features or services to the WordPress weblog, which can be seamlessly integrated with the weblog using access points and methods provided by the WordPress Plugin Application Program Interface (API).

Forget about looking for a class to extend. All the plugins I looked at were collections of functions. Here are some things I learned about WordPress plugins that may be useful for a newbie like myself.

The bar to entry is very low

It was surprising how easy it was to get WordPress to recognize a new plugin. This is a testament to the simplicity of the plugin architecture in WordPress. All you need is to create a new PHP file inside the plugins folder in your WordPress installation and write a comment block on it. Although not a requirement, it is always a good idea to put your plugin files inside a folder. The comment is the plugin information header.

You can now go into the WordPress admin panel and activate it (from the inactive plugins list). You will now see the plugin activated. Of course it doesn’t do anything, but that was incredibly easy!

Activate the plugin from the Admin Panel

Plugins are just a collection of functions

The best way to learn how to write a plugin is by studying other plugins. Good starting point are akismet and the hello dolly plugins that are included in the default installation. You will quickly see that most plugins have no class definitions, but they are just a collection of functions.

Plugins can take two forms:

1. Plugin as a library.
2. Plugin as a dependency injector.

1. Plugin as library

This is the simplest form of a plugin. A library is simply a collection of functions. The client, a WordPress template in this case, can call the functions. Each function call does some work and returns control to the client.

Template tags are calls to WordPress functions that do something or return some value back to a template. For example,  the bloginfo template tag is a function implemented within WordPress and returns information about the blog based on passed parameters. The ‘name‘ parameter, shown below,  returns the name of the blog.

bloginfo('name');

Custom template tags can be implemented in plugins. This is a super easy way to extend WordPress functionality. All you need to do is implement a function in your plugin with the name of a template tag you come up with (make sure it is unique – more on this later). The following figure shows the index.php template calling the get-the-image template tag. The get-the-image function is implemented in the Get the Image plugin.

2. Plugin as dependency injector

This is a more powerful method of extending the functionality of WordPress. Instead of waiting for the template to call the plugin function, the plugin injects the function into the template. Dependency injection using plugins is called hooks in WordPress. There are two types of functions that can be injected or hooked into wordpress: Actions and Filters.

Action functions can be hooked into specific events in WordPress. That means, the function is called or triggered by a specific WordPress event. For example, you can write an action function that informs different search engines when a new article is posted. The  plugin function will hook into the publish_post event. The events that can trigger an action function are numerous. Refer to the Plugin API/Action Reference for the list.

Filter functions can be hooked into WordPress  to pass content through the function before being output to the web page. For example, if you want to filter out profanity in comments, write a function that takes the comment text as a parameter and returns the clean content. Now you can hook this filter function to the comment_text filter hook so that it is called before comment text is published on the page. Refer to the Plugin API/Filter Reference for the list of filter hooks.

I won’t go into detail on writing plugins as dependency injectors. The plugin API documentation provides a good introduction. A good example on how to write action functions is to take a look at the hello dolly plugin. The book on WordPress Plugin Development by Vladimir Prevolac is quite good and explains action and filter functions very well ( check out the sample chapter ). Above all, download some plugins and take a look at the code – you will learn some interesting techniques.

Choose plugin and function names carefully

Make sure you use a unique name for your plugin and its function names. PHP  and WordPress don’t take kindly to duplicate function names. The plugin will just not load and you will be left wondering what happened. Searching the WordPress plugin directory before settling on a name is not a bad idea. The dash ‘-’ is the recommended separator for words in the filenames and function names for plugins.

Make sure the plugin function exists before you call it

This is also known as:

Looking for a black cat in a dark alley that isn’t there

This is most important for library type plugins that are called directly from templates. The template doesn’t know if the plugin exists or if it is activated. Therefore, it is a good idea to first check if the function is available before calling it from a template. The PHP statement in the template should be of the form:

if( function_exists('get-the-image') ) { get-the-image(); }

The tag function  ’get-the-link‘ will only be called if it exists. There is a tight coupling between the template tag and the plugin where the function is implemented. You need to manually add the tag to the new theme templates if you switch themes.

One of the big advantages of injector type plugins is that the hooks are created at runtime. The template files don’t have to be modified to call the functions. In fact, the template doesn’t know anything about the plugins or the hooks. Therefore, themes can be switched without requiring any changes in the template files.

Get the Image Link plugin

Let’s get back to the issue at hand. The purpose of the new plugin is to implement the get-the-link template tag by calling the get_the_image function in the  Get the Image plugin. We need to return the URL of the image as opposed to the image element.

It is a good idea to take a look at the README file for the Get the Image plugin before proceeding. First thing to note is that the function takes query string style parameters (as opposed to function style parameters). Query string style is desirable when a function has many parameters. The second issue to note is the ‘echo’ parameter which is set to true by default. This causes the function to echo the image element text to the output buffer inside the function. We need to set this to false.

The plugin will consist of one function called get-the-link that calls get-the-image in the Get the Image plugin. It then parses the image element to extract the src attribute using regexp and returns it.

function get_the_link($args = array())
{
	if (function_exists('get_the_image'))
	{
		$args = wp_parse_args($args);
		$args['echo'] = false; // prevent echo output
 
		$imageElement = get_the_image($args);
		$pattern = '/src=(['"])?(.*?)\1/i';
		preg_match($pattern, $imageElement, $matches);
 
		return $matches[2];
	}
}

You can now call the get-the-link template tag from a template and pass it as a parameter to the timthumb script for resizing. Look at the timthumb.php comment block for parameters and usage. The timthumb.php file is included in the hijriah theme.

I must say that writing a library type plugin was much simple than I thought. So, don’t hesitate to give it a try as the more you learn, the more comfortable you will be about customizing WordPress. I learned a lot about theme development during this process and now feel comfortable enough to develop a custom theme. I’ll write about that experience in a future post.

Download the Plugin