Multipurpose Knife

9-minute read

A Custom Utility Plugin for your ClassicPress Site

When adding bits of code to your ClassicPress site, you might think to add it to your functions.php file. Is there another way? A better way? Join me in this deep-dive discussion of utility plugins – then we’ll build one to get you started!

In this article, you’ll find out why you should almost never place code into your functions.php file, and learn a rock-solid alternative approach that you can always count on. I’ll show you how to ensure maintainability, portability, and sanity when adding snips of code to your site – by creating your own custom utility plugin. There will be some discussion before and after the examples, so if you’re just looking for the code, here’s your jump. Or, if you’d like to download a ready-made utility plugin, you can do that, too. Let’s get it!

What is a utility plugin?

A utility plugin is a plugin that adds, removes, or alters the functionality or behavior of your ClassicPress website. “What kind of functionality,” you might be wondering? Any kind! But, let’s not focus on that just yet. Before moving on, let’s just take a quick look at several great benefits of using a utility plugin:

  1. creates a safe container for your code snips, and
  2. can be re-used with few changes, and
  3. provides a way to start creating plugins, and
  4. shed a bad habit and replace it with a best practice.

Why not just use the functions.php file?

When you add code to your theme’s functions.php file, you’re actually decreasing the maintainability of your site. Let’s say your site is using a non-child theme; your code can be erased when you update the theme. Or, if you ever switch themes, you will lose all your code snips unless you copy them over one-by-one. Everything might seem fine for now, but will you remember those obscure code snips a year or two from now when you decide to go with a new theme? Will you even notice that something broke? If you place your code snips into a utility plugin, you effectively bypass all these concerns.

What goes into a utility plugin?

It’s important to realize that everything doesn’t automatically go into a utility plugin. There are legitimate cases for placing code into your functions.php file. If you’re not sure whether your code snip should go into your utility plugin or your theme’s functions.php file, ask yourself this one question:

Should this code still run if I change my theme?

If the answer is yes, the code goes into your plugin. If the answer is no, the code goes into your theme’s functions.php file. Before long, you may realize that the functions.php file is often recommended because it’s easy, rather than because it’s a good idea. The above question makes it plain where the code belongs.

Utility Plugins are Versatile

The term utility plugin is somewhat nebulous. Let’s clarify that a utility plugin can be used to add, remove, or modify functionality. In fact, the plugin we’re about to build will be modifying a bit of core functionality, rather than adding or removing any features. More on that shortly.

If you build sites for a living, a utility plugin can save you time and effort. You will often be able to reuse some or all of the plugin’s code on many sites. After you’ve built a utility plugin a few times, you’ll start to notice similarities from site to site and this can lead to your creating a boilerplate utility plugin that you can drop into any site. Then, you can tweak each site’s plugin to meet its needs without having to reinvent your basic wheel each time.

Using Procedural PHP in a Utility Plugin

It is completely fine to use either procedural PHP or object oriented PHP for your utility plugin. To me, it usually makes more sense to use procedural PHP due to the fact that the code will likely be a bunch of unrelated – or quasi-related – code snips.

For example, the utility plugin might be doing everything from redirecting users after login to changing the dashboard footer text to removing items from the admin bar – and much more. These modifications aren’t closely related, so, procedural PHP is well-suited for the task. That said, I see no harm in using OOP, if that’s your preference.

Ensuring Your Utility Plugin Plays Nice

To keep your code safe from collisions with other code in the system, it’s a good idea to use prefixes or namespaces. Prefixes are somewhat dated, however, they do prevent most collisions. That said, namespaces are actually built for preventing collisions. The choice is yours, however, the examples below do depict the namespaced approach.

If you’re not sure how to work with namespaces, no worries! The context of a simple utility plugin is the perfect way to get started. I’ve also written extensively on using namespaces in ClassicPress plugins – look for it in the upcoming weeks!

Preparing a Utility Plugin for ClassicPress

I prefer to build plugins with a live ClassicPress installation on a staging or local server. This allows me to add code snips and test them in a safe space. The following steps assume that you are also building your plugin on a working ClassicPress installation.

Step 1: Create the plugin file structure.

The first step in creating a utility plugin is to create a new directory for it. It is a common ClassicPress convention to use hyphens (rather than underscores) in place of spaces, so, if your plugin was called Custom Utility, your directory would be named custom-utility. Create your new directory inside your /wp-content/plugins/ directory.

Step 2: Create the default plugin files.

Inside your new /custom-utility/ directory, create two blank PHP files with the following names:

  • index.php
  • custom-utility.php

The index.php file will be a blank file; this prevents anyone from listing the directory contents. The custom-utility.php file will hold your code. With these files in place, the basic plugin structure is complete.

Step 3: Create the plugin header section.

To register your plugin with ClassicPress, you must include a specific PHP comment at the beginning of your primary plugin file – in this case, custom-utility.php. We refer to this comment section as the plugin header. See the code block below and copy the example plugin header into your primary plugin file. Be sure to change the text and URL to reflect your own plugin’s name and values, and then save the file. Note that there are also a number of other values that can be used in a plugin header, if you’re feeling extra ambitious.

Step 4: Test the plugin activation and deactivation.

With your plugin header in place, you can now navigate to your plugin admin page at Dashboard > Plugins and you will see your plugin in the list. Go ahead and click to Activate it. The plugin doesn’t do anything incredibly useful yet, but, you do have a working plugin! Your plugin can now be activated, deactivated, and deleted. Give it a try! But waitdon’t try the Delete action – that would actually delete the files you’re working on!

ClassicPress Plugin Administration
ClassicPress Plugin Administration Screen

Adding Code to the Utility Plugin

With the utility plugin’s first code snips, we’ll be addressing what some consider a security issue. Let’s quickly go over this issue, so, you can be familiar with why this code is important, instead of just copying it into your plugin.

Let’s say a hacker comes along. If that hacker attempts to log in with an incorrect username or password, the resulting error message reveals whether it was the username or the password that failed. In other words, this tells the hacker which part (username or password) didn’t fail. This is a way to discover valid logins for further targeting.

ClassicPress Login Error
ClassicPress Login Error Messages

Step 1: Add a namespace.

Step 2: Write a function to change the login error text.

Step 3: Hook your function into the system.

And, with that, you now have a working utility plugin that does something useful. Of course, this is a starting point – the code snips that go into your own utility plugin will vary.

How Much is Too Much?

Now that you have the power of a utility plugin in your hands, it can be tempting to add a million little things to your site. It’s totally possible. Just add more functions and hook them into the system…it’s your new “functions.php”, after all. Of course, this begs the question: how much is too much? Glad you asked.

If your utility plugin is growing into the thousands of lines, you might consider moving some of it out into plugins. If you find the need for an admin panel in the dashboard for your utility plugin, you may want to rethink what all you have included. Of course, it’s entirely up to you. I follow a simple guideline:

If a particular functionality needs to survive a theme change, but, it’s not enough functionality to warrant a dedicated plugin with settings, then it goes into the utility plugin as a code snip.

Wrapping Up

At this point, I hope you feel confident in creating and using your own utility plugin. By now, you understand the reasons behind using a utility plugin, the methodology involved, and the questions to ask yourself before adding any custom code. Take pride – you just added a notch to your developer tool belt.

What do you think?

Is the idea of using a utility plugin appealing, or have you been using them all along? How about handling code collisions: do you use prefixes, namespaces, or object oriented PHP? What sorts of things will you add to your own utility plugin? I’m curious to hear your thoughts – let me know in the comments!

4 comments on “A Custom Utility Plugin for your ClassicPress Site”

  1. A commenter said:

    Great article.  Another option (which I prefer for most things) is to use mu-plugins.

    A mu-plugin or “must-use plugin” is a single .php file that lives in wp-content/mu-plugins/ folder – you may need to create this folder on your site.

    Example: wp-content/mu-plugins/some-small-feature.php

    Then you just paste your code in that file.  You can add the plugin header comments if you want, but it’s not required.


    • No need to enable or disable the plugin (in fact this isn’t possible).  If the file is present then the code is loaded.
    • Once a mu-plugin is working for a given feature then it can be easily and quickly enabled on other sites by just copying/updating the file.


    • May be harder to recover from coding errors – you would need to use an FTP client to fix or remove the file with the error.


    More information:

    Code Potent said:

    Hey James, thanks for stopping by. You make good points and I appreciate your enumerating the pros and cons. I’ve used must-use plugins a few times – very handy when the site owner requires higher than editor level capability. One benefit I hadn’t considered is the improved efficiency for those who are managing large numbers of sites – insta-activation, for the win! Also, good to know the header comment isn’t required for mu-plugins; I’ve always just thrown it in out of habit.

  3. A commenter said:

    Nice Guide at codepotent, I have always hard code into themes all my life, perhaps because I don’t change themes, a custom one. Even then, you’ve convinced me how a plugin can be useful. I should start removing some functions into plugins now.

    • AUTHOR
      Code Potent replied:

      Hi Ahmed, I do see your point about when you’re using a custom theme internally – it’s not as critical as it is with a theme that is released to the public. However, I’m glad to hear this helped you understand the reasoning behind placing custom code into a utility plugin rather than functions.php. One thing that’s really handy is having the ability to “turn off” your code snips by deactivating the utility plugin – this isn’t as easily achieved when that code lives in functions.php.

Leave a Reply

Your email address will not be published. Required fields are marked *