Code

3-minute read

Convert a Code Snip into a ClassicPress Utility Plugin

A beginner’s guide to converting procedural PHP into namespaced or object-oriented PHP – with a very understandable apples-to-apples comparison! This will be a primer for a more in-depth article on using namespacing in ClassicPress plugins.

If you’re like most, you will have searched the web and found code-snips for your ClassicPress website. Let’s say you wanted to change the footer text in the dashboard. After a quick search, you find the following code-snip with instructions to place it into your theme’s functions.php file.

First off, code-snips should go into a utility plugin, rather than your theme’s functions.php file. This is achieved by adding a short comment at the top. Additionally, the function name is prefixed to prevent code collisions. Here’s what that looks like.

Great! The code-snip is now held safely in a utility plugin that can be activated and deactivated in your dashboard. The above example is written in basic, procedural PHP and, because the function name has a prefix, it is nicely isolated from clashing with other code in the system.

Prefixing your code in this way is usually enough to prevent collisions, so, if that’s all you’re after, you can stop here. However, also note that, as you find new code snips, you can add them to this same utility plugin; there’s no need to create another. Now, git ta steppin’, … the rest of us want to namespace this thing! So, let’s!

As you can see, the big difference is that the prefix is used in the namespace instead of the function name, and the __NAMESPACE__ magic constant is used when hooking the function into ClassicPress. This is handy when your plugin grows to contain a lot of functions; you can change the namespace in one single place, instead of changing a bunch of prefixes. Namespacing is the actual built-in PHP method for isolating, or encapsulating, our code, but, more often, you’ll see code being encapsulated with object-oriented PHP. Here’s that same code-snip as an object-oriented plugin.

In the case of object-oriented PHP, you can simply use the __construct() (or similar initialization) method to hold your action and filter hooks. I quite like this style of keeping all the actions and filters together and is the method I tend to use most. And, the $this variable is extremely handy when you want to pass data back and forth between the various methods (functions) inside the class.

Wrapping Up

As you can see, a code-snip can be added to your ClassicPress site without having to add it to your theme’s functions.php file. Placing your code-snips into a utility plugin is a better practice and gives you a quick means of activating and deactivating all of them quickly. And, of course, there are various ways to encapsulate our code and achieve the exact same result. There’s no requirement to use one method or another. You decide. As long as you have at least used unique prefixes, as shown in the first plugin example, you can be reasonably sure your code will be safe from collisions…and safe from theme changes, too!

What do you think?

Was it helpful to see a simple code-snip converted into a plugin? Did it answer any questions to see that plugin converted into other styles of code? Do you have a preference over which style to write your code? I’m curious to hear your thoughts – let me know in the comments!

Note: the header comment used in the examples here was very basic. There are more fields that can be used.

4 thoughts on “Convert a Code Snip into a ClassicPress Utility Plugin

  1. Thanks for this tutorial! I am in the process of writing a little utility plugin and your clear explanation has given me the chance to really understand differences. For now I think I will go with just prefixes… I have just couple simple ideas.

    1. You’re welcome. I’m glad you found this of use. …and you’re perfectly fine to stick with prefixes. You may have a couple of simple ideas now, but, as you learn more, your ideas will start flowing much more than you can even keep up with. Mark my words! 😀

  2. This is a nice and simple article for any new plugin developer. However, what are your thoughts and take from the old age war of having only variables in the constructor()?

    1. The purpose of the constructor is to ensure that the new object is created with its properties (ie, internal variables) set, so, in 99% of cases, I would say, “If it’s not setting a property of the object, then it doesn’t belong in the constructor.” I also tend to avoid putting logic in the constructor. In most cases, my constructors will have just a single invocation of $this->init();, which is where I initialize the plugin (ie, add all my actions and filters.)

      In the case of a utility plugin (as seen above,) which usually consists of a bunch of unrelated code-snips, there’s not usually any variables to set up – indeed in most cases, the constructor will never be used other than to initially create the object, so, I don’t mind if there are other things (such as add_action and add_filter or random $variables) in it.

      Of course, there are always going to be a lot of opinions on it, so, my advice is to determine how it makes the most sense to you, and just keep consistent across your work. Consistency is far more valuable than what-is-done-where.

Leave a Reply

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

shares