Integrating Payments into WordPress, Part 3: Build Your Own PayPal Plugin

This is the third and final article in my series on using the WordPress weblog and CMS system.

In the first article I introduced WordPress (aka “WP”), provided links to documentation to help you get up to speed with WP, and then showed you how to install and start using it. In the second installment, I provided an overview of WP plugins, made some general plugin recommendations, and showed you how to search for PayPal-related plugins in the WordPress Plugin Directory. I also demonstrated two popular PayPal plugins, one a shopping cart, the other a plugin to accept donations.

This time I want to detail the WordPress plugin model. We’ll get our hands dirty with some code for an example WordPress plugin. And by the end, you’ll know how to go about creating a simple WP plugin of your own.

A note about PHP

In order to hack around in WordPress, and especially to modify or write new WP plugins, you will need to have some PHP programming knowledge.

The good news is that PHP is a relatively straightforward language. There are also some very nice resources for getting up to speed quickly with it.

If you just want a minimalist, WP-oriented introduction to PHP, I’d recommend you work through Adam Brown‘s “PHP Tutorial for WordPress Users“. If you want to go further, dive into the official PHP manual and tutorial. Those resources should give you the prerequisite PHP knowledge to work through the rest of this article.

Understanding The Loop

There’s one more major item you need to understand before we dive into WP plugin code. That item lies at the core of how WP renders post contents. It is The Loop.

The WP Codex summarizes The Loop like this:

The Loop is used by WordPress to display each of your posts. Using The Loop, WordPress processes each of the posts to be displayed on the current page and formats them according to how they match specified criteria within The Loop tags. Any HTML or PHP code placed in the Loop will be repeated on each post. When WordPress documentation states “This tag must be within The Loop”, such as for specific Template Tag or plugins, the tag will be repeated for each post.

Some plugins operate within The Loop, others outside of it. As you design a plugin, keep The Loop in mind and make sure that if your plugin will be manipulating post contents display that it’s setup to be executed within the cycles of The Loop. If you have any questions about what The Loop is or how to interact with it, I would encourage you to take your time reading through its Codex page and the resources linked to from it including “The Loop in Action“.

Note that the “The” is always capitalized in “The Loop” because of its great importance in the WP system. A bit high and mighty I guess, but just go with it.

The anatomy of a WordPress plugin

It’s time to start looking at plugin code. The Codex page “Writing a Plugin” provides a high level overview of the steps required and where to go to learn more about each. The first few steps you need to take are to create:

1. A unique plugin name; you should search through the Plugin Directory to make certain your name is unique so that you can avoid naming collisions later
2. One or more plugin files; you must have at least one PHP file containing your plugin code but you may have additional files (JavaScript, CSS, images, etc.)
3. Optional: A readme.txt to provide more information if you list your plugin in the Plugin Directory; the format for your readme is described here
4. Optional: A homepage for your plugin if you are going to distribute it to others; this page should describe what the plugin does, how to install it, version compatibility and prerequisites, how to use the plugin, etc. and you may either use your Plugin Directory page or create a page on your own site for this

Let’s look at an example plugin. We’re going to examine the first plugin ever written for WP, “Hello Dolly“. It is the oldest WP plugin, created by the founding developer of WP. It is also a very good plugin to examine because it’s simple and it’s installed with WP installations by default. If you’re following along with this article series and have installed WP, you should already have a copy of “Hello Dolly” on your server. If for some reason you don’t see it listed on your server’s plugin administration page (http://yourserver/wp-admin/plugins.php) you can install it from its Plugin Directory page (click here).

“Hello Dolly” consists of only one PHP file, hello.php, contained within a hello-dolly directory in the downloadable ZIP distribution.

At the top of the Hello Dolly source code listing you see some standard plugin information. This plugin info header lets WP recognize the plugin, add it to the plugin administration screens, and allow you to activate/deactivate it on your server. The header format is detailed on “Writing a Plugin” as:

<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2
*/
?>

Note that at least Plugin Name must be provided. Some plugins may omit one or more of the other header lines. Hello Dolly, for instance, does not provide a License line.

Next in the source you’ll see the lyrics to the song “Hello, Dolly!” and some code that splits the lyrics up into lines based upon newline characters. The code then randomly chooses a line to display using the code below.

After the lyric logic, we get into the meat of the plugin, the hello_dolly and dolly_css functions. These two functions hook into the WP system via action “hooks” that set those functions up to execute when certain actions occur within the WP system. I discussed the WP Plugin API’s action and filter hooks in the previous article in this series; please refer to that article if you need a refresher on WP hooks.

For our purposes here, the key point is that hello_dolly hooks into WP via the admin_footer action (executed at the end of the administration panel) while dolly_css hooks in via admin_head (executed in the HTML head section of the admin interface).

In other words, each of these functions is registered as a callback such that when the specified administrative interface action occurs, they are executed and the previously chosen line from the song is displayed in the upper right portion of the WP admin interface.

Wrap your brain around this critical callback functionality and WP plugin programming becomes fairly straightforward.

By the way, the same gentleman that provides the “PHP Tutorial for WordPress Users” discussed previously also maintains a very useful “WordPress Hooks Database“. Highly recommended for learning about any and all of the large number of action and filter hooks built into WP and available for your use.

Click here to read the complete article on the PayPal X Developer Network including how to build, deploy, and test an example WP plugin that fetches a PayPal account balance.