If you have ever worked in a professional development shop, you are probably familiar with the careful preparations, discussions, wireframes, and mock-ups that are made before any code is written. Projects born of haphazard random hacking are always harder to upgrade and maintain, so it is worth your time to plan your actions before writing a single line of code.
The following are a few important aspects to have in mind when starting development of your plugin:
Interfaces
Localization
Documentation for the developer
Version control
Environment
Tests
Security
As you write code, you should constantly ask yourself, "How should this component be used?" If you are coding a particular function, you should choose what the input and output should be to make it as easy to use as possible. If you are planning a particular plugin, close your eyes and try to imagine every detail of how it should look once it is finished. What configuration options does it need? How many buttons? What will each button do? Choosing how a user will interact with your code can be broadly described as "defining the interface", and it is one of the most important aspects in planning your project because you should strive to "code to the interface". The concept is subtle, but the point is that if you have designed an interface that is easy to use, your plugin will be easy to use, and its code will be easier to maintain.
When you think about interfaces, think about the WordPress API—it is a series of functions that define how you interact with the WordPress application. While the code within each function may change between versions, so as long as the inputs and outputs (that is "the interface") remain the same, all the code using those functions will continue to work.
Even if you never intend to release your code publicly, it can be helpful to isolate any text that is used for messaging and might at some point be translated. If you are curious, you can skip ahead to the chapter on internationalization.
As you write your plugin, be vigilant about documentation. Most developers do not include enough comments, and some include too many. At a minimum, you should include a synopsis of the plugin itself and list the expected inputs and outputs of each function so that it is clear to anyone looking at the comments what the function does and what data types it requires. If you've followed the advice presented here so far, your code will be broken down into bite-sized "units" that are easier to debug and easier to document. If you find that you are documenting a function that does more than one task, chances are good that you did not break down the functionality into a small enough unit. We have included a section on how to write effective documentation in a later chapter.
On any software project, it is useful to store versions of your files using one of the common version control applications such as Subversion (SVN), GIT, or Mercurial. The WordPress plugin repositories use SVN, and it is one of the most popular tools, so if you know you will be publishing your plugin, it may save you some time to use SVN right off the bat.
No matter how you do it, make sure that you are storing all revisions of your work so that you can easily roll back. Indeed, in professional projects, one of the first things that gets set up for collaborators is the version-controlled code repository. If you know you are going down this route or if you just want to brush up your chops, you may want to spend around $50 and get a good client for your system. Mac OS X ships with SVN on the command-line (and the Coda editor includes a basic SVN client), but you can also download Versions (http://www.versionsapp.com). Windows has the well-liked TortoiseSVN (http://www.tortoisesvn.net), while SyncroSVN is available on all platforms (http://www.syncrosvnclient.com). GIT also has client software available on all platforms.
We have included a chapter on SVN later in this book, so feel free to refer to it if you need to get your code versioned.
Just as you should consider the interfaces and possible translations of your code before getting too deep into it, you should also consider the environment on which it will be deployed. Does your code need to work on a specific version of PHP? Does it need to work across a series of load-balanced servers where the default PHP session management won't work? Does the destination environment have all the PHP modules that you have on your development machine?
It is common practice in software development to set up a development server that mimics the production server exactly. Unless you do additional tests, the only environment on which your plugin is guaranteed to work is the one you used while writing it. If you ever write plugins for paying customers, be sure to allow time to test your code in the environment(s) where it will be used.
Whether informal or not, tests are an integral part of any application. If you have structured your code well, it will be easier to test. Later on, we will talk about writing tests to ensure that your plugin functions properly, but it is also very worthwhile to construct informal proof-of-concept tests as you develop.
Just as an artist will draw a few studies before he paints his masterpiece, it is useful for the developer to isolate tricky bits of code into a separate test or proof. We recommend saving these little proofs in a separate directory and keeping them along with your other project code. They can become valuable notes for you as you progress in your education of PHP development.
Web application security is a massive topic that goes far beyond the scope of this book. Experience is the best teacher, and we encourage you to educate yourself as much as possible when it comes to understanding vulnerabilities. We are devoting only a small amount of time to cover some of the most common exploits. You don't have much control over the underlying technologies that your plugin runs on (that is PHP, MySQL, or WordPress itself), so you should focus your attention on writing your code securely. The following scenarios represent the most commonly exploited areas in a typical web application, but remember: security is a journey, not a destination. No technology or code can ever be guaranteed to be 100% secure, but there are steps you can take to avoid the most common pitfalls.
This most often comes up when repopulating forms after failed validation and it is often the key ingredient in a cross-site-scripting (XSS) attack. Be extremely careful any time your code handles data supplied by the user. This can be data from the $_POST, $_GET, $_REQUEST, $_COOKIE, or even from the $_SESSION arrays. If you print any of this data to the page, you must make sure that you have filtered out any malicious content.
Consider this little bit of code:
<?php print $_GET ['x']; ?>
That bit of code is deadly. Printing raw request variables is all it takes to convert your site into a distributor of scum and villainy, infect computers with viruses, and get your site blocked by Google.
A better example shows how to force the value of a variable to an integer using type-casting, rendering harmless any hacking attempt:
<?php print (int) $_GET['x']; ?>
When handling user-supplied data, you will certainly become intimately familiar with regular expressions and the preg_match()
and preg_replace() functions. Regular expressions represent another topic that is beyond the scope of this book, but keep an eye on our plugins for examples on how they might be used.
This can crop up in search forms, profile pages, surveys, or any other form that interacts with the database. Consider this query:
$query = "SELECT * FROM wp_some_table WHERE username='" . $username . "'";
If you did nothing to filter the value of $username, then it is entirely possible that the variable could contain multiple queries instead of just the single username you expected. This could lead to your database being inadvertently read, deleted, or altered. Sending unfiltered user input directly to the database is the prime ingredient in a SQL-injection attack.
The risk can be virtually eliminated if your code uses "prepared statements". Instead of sending arbitrary strings to the database for execution, prepared statements first prepare the basic query and then accept only variables that complete it. Prepared statements are only possible if your web server has a more mature PHP-MySQL driver installed, such as mysqli, and your code is written explicitly to use them; WordPress does not, so be very careful if you ever start constructing your own query strings to send to the database. It is highly recommended that you use WordPress' built-in database accessor functions whenever possible. We have some examples of these in our plugins.