In a recent search for a WordPress chat plugin, I came across several “best practice” violations. Sometimes, ignoring best practices just gives future developers a headache. In other cases, it results in a inexplicable parse errors or PHP printing onto the user’s page.
The issues are almost always due to internal server configuration. Just like HTML and CSS, you should follow best practices in PHP to ensure compatibility on any server and save you – and your users – some trouble.
Use only Long Tags
<? echo(“Foo!”); ?>
For some reason, at some point in the past, someone decided short tags were a good idea. This is, without a doubt, the simplest fix of them all. In your php.ini file, there’s an option named short_open_tag. If you’re running a local server, you might have this option on and you might be able to get away with using it.
Most web hosts have the option off. The notes accompanying the option in php.ini tell you to keep it off.
For portable, redistributable code, be sure not to use short tags.
The fix is beautifully simple. Always open your PHP statements with <?php instead of <?. You’ll never have a problem with short tag compatibility.
Don’t Close PHP
While not as dramatic as the short tag fix, sometimes ending a PHP file with a closing ?> can cause header errors. Once you end the PHP block, everything else is considered output. If you’ve next document sends headers, then you’ll get beautiful, infuriating Headers already sent errors. By leaving the block open, you don’t need to worry about the possible white space disturbing the headers for the next function.
There are exceptions to this. In a WordPress theme, for example, you should always close PHP blocks. Since you can never be sure that the subsequent template start with PHP and not HTML, it’s best to close them all and meticulously remove lines afterward.
Be Selective with Your Echo Statements
There’s no graceful way to approach the issue of outputting HTML or JavaScript from a PHP function, especially if you need to echo PHP in the middle of the HTML (as in the WordPress Loop). You have three options
- Temporarily exit PHP for straight HTML and echo PHP in the middle.
- Echo HTML lines and denote PHP in the middle.
- Echo giant chunks of HTML and denote PHP as needed.
You should [almost] never use the third option. It’s messy, error prone and, depending on the code, can cause apostrophe matching issues. I cry a little when I see this option used for a plug-in’s JavaScript. Bonus best practice: put JavaScript in its own file and include that.
To determine whether you should use the first or second option, consider the composition of the line(s). If you have more HTML than PHP and just need to echo a variable or three, you should opt for the first. However, if you have lots of PHP – functions, ternary operators, loops, etc. – you’re best off using the second.
Use Functions
When you’re making major overhauls to a WordPress (or any OS software) template, the temptation is to throw it in for easy access later. You wrote it, you know what it is, no problem, right?
Always assume that you won’t be the first, last and only person to ever touch the code. Maybe next week your brother-in-law’s cousin’s son will ask if you can start blogging with you. Or something breaks and you need to hire a coder to fix it. Or you get an offer for mad cash and sell it to retire in Zimbabwe.
If you add functionality that requires you to dedicate more than a single line to PHP, you absolutely must a) put it in a function, b) put that function in the template functions file and c) give the function a really obvious name. And, of course, you really have to
Comment Your Code [obligatory reminder]
Way back when, while learning how to drive, my Dad used to joke that I should never let the other guy know what I was doing. If you’ve ever been rear-ended because you forgot to turn on your blinker, you’ll know what a really bad idea this is.
The single worst thing about working with someone else’s code is a complete lack of comments. I don’t look for dissertations on the value of their selected approach, but it would be nice if they’d let me know what they’re doing.
At bare minimum, you should comment each function. Let future developers know what the function does. If you use a relatively obscure native WordPress function, add a comment with its file name and line number, the Codex URL or a short blurb on what it is.
Sidesparks, a chat plugin, gives very helpful comments.
/*
* This will generate a Sidesparks Textlink with the specified link element
* it will either use get_the_tags() in case it returns an array, else the title
*/
function generateSidesparksLink($link, $print = true) {…
MyScorePresenter, a plugin for flash games, gives less helpful comments.
/*
* @brief Expand Score data
*/
function myscore_expand_template($template, $score_result, $score_name) {
See the difference? Sidesparks tells me exactly what the function does. MyScorePresenter gives me no context or instructions. It actually doesn’t matter at this point which plugin has the “better” code. All that matters is that in one, I can figure out what a function does without reading the whole thing or wading through code.
There’s a bonus here for you: If you comment your code really well, you’re less likely to receive complaints such as “I installed it and my page turned white when I clicked x.” Instead, you might receive something like, “I kept getting a white page after clicking x, so I found the function that handles x in file y on line z and did some magic fix you can see in the new version that I attached.”
Do you find the lightbulb icon to be extremely awesome? I also did and was quite tickled to find it. You can download it – for free! – along with the rest of the Sienna icon pack from Web Designer Depot.
Feedback