Best Practice For Adding Custom Functions

"Where should I put custom functions...in my theme or in a plugin?"

That's a good question. I've seen lots of WordPress tutorials, and even the WordPress Codex, recommend adding custom functions to your theme's functions.php file.

While that method does work, it can also cause problems when you change your theme to something else. The new theme won't have that code in its functions.php file, and your custom functionality will just...you guessed it...stop functioning.

In early February 2011, Justin Tadlock wrote an awesome tutorial about a great alternative to using the functions.php file - Creating a custom functions plugin for end users.

Go read it, then come back here and I'll walk you through adding the first custom code snippet to your shiny new custom functions plugin.

Step 1: Create your custom plugin

I've created a blank plugin file along the same lines as the sample plugin in Justin's tutorial. Copy the following into a blank text file and save it as my-custom-functions.php:

<?php
/*
Plugin Name: My Custom Functions
Plugin URI: Your site URL here
Description: A simple plugin that contains all the awesome little functions that I use to make my site work <strong>my way.</strong>
Author: Your name here
Author URI: Your site URL here
Version: 0.1
*/
 
/* Disallow direct access to the plugin file */
 
if (basename($_SERVER['PHP_SELF']) == basename (__FILE__)) {
	die('Sorry, but you cannot access this page directly.');
}
 
/** START ADDING CODE BELOW THIS LINE **/
 
/** STOP ADDING CODE NOW**/
 
/* That's all folks! */
 
?>

Make sure to change the sample text for the plugin URI, author name and author URI so that it reflects your information.

Step 2: Let's add code!

For the example, I'll add code to only show the admin bar when in the WordPress admin area. Hat tip goes to one of my commenters, Clay Campbell, for the idea.

Add the following directly after the /** START ADDING CODE... **/ line:

/* URL: http://wphidedash.org/2011/04/best-practice-for-adding-custom-functions/
    Set the admin bar so it only shows in the admin area, not the public-facing site.
    This overrides the admin bar settings on the profile page for all users. */
 
function my_custom_admin_bar_setting() {
	if (is_admin())
		return TRUE;
	else
		return FALSE;
}
 
add_filter ('show_admin_bar', 'my_custom_admin_bar_setting');

This function will override any admin bar settings that you or other users make on your profiles. It works in both WordPress single user and WordPress Multisite (activated on one site, network-activated, or installed in the mu-plugins folder to run network-wide).

When adding custom functions that you've found on the web, you might include the URL where you found the code in the opening comment, along with a short description of what it does, so you don't have to do the "needle/haystack" search if the code doesn't work right.

Step 3: Upload/activate your custom functions plugin

Justin's tutorial suggests using either the /wp-content/plugins/ folder or the /wp-content/mu-plugins/ folder to house your shiny new custom plugin.

If you aren't familiar with the mu-plugins folder, I suggest reading both the explanation Justin has in his tutorial (see Option #1), and the awesome explanation from Andrea Rennick of WordPress Must-Use Tutorials - What is the mu-plugins folder? - before choosing this option. A word of caution - any plugin placed there runs automatically (no activation required), and, for plugins downloaded from wordpress.org, there are no update notifications if a new version of that plugin is released. If you aren't comfortable with that, then you can place it in the regular plugins folder (Option #2), and activate it like any other plugin.

Wrapping things up

And there you have it - a great way to house all of your custom functions AND ensure that they'll keep on working, no matter how many times you upgrade or switch your theme.

Who said best practices have to be hard?

This entry was posted in WordPress and tagged , . Bookmark the permalink.