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.

The Tutorial

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.

function custom_footer_text($text) {
    return 'The best debugging tool is a good night\'s sleep.';
}
add_filter('admin_footer_text', 'custom_footer_text');

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.

<?php
/**
* Plugin Name: My Utility
* Description: A safe place for code-snips.
*
* Note: save file to /wp-content/plugins/my-utility/my-utility.php 
*/
function yourownprefix_custom_footer_text($text) {
    return 'The best debugging tool is a good night\'s sleep.';
}
add_filter('admin_footer_text', 'yourownprefix_custom_footer_text');

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!

<?php
/**
* Plugin Name: My Utility
* Description: A safe place for code-snips.
*
* Note: save file to /wp-content/plugins/my-utility/my-utility.php 
*/ 
namespace YourOwnPrefix\Utility;
function custom_footer_text($text) {
    return 'The best debugging tool is a good night\'s sleep.';
}
add_filter('admin_footer_text', __NAMESPACE__.'\custom_footer_text');

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.

<?php
/**
* Plugin Name: My Utility
* Description: A safe place for code-snips.
*
* Note: save file to /wp-content/plugins/my-utility/my-utility.php 
*/
class Yourownprefix_Utility {
    // Add your actions and filters to this method.
    public function __construct() {
        add_filter('admin_footer_text', [$this, 'custom_footer_text']);
    }
    public function custom_footer_text($text) {
        return 'The best debugging tool is a good night\'s sleep.';
    }
}
new Yourownprefix_Utility;

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.

This tutorial has been provided by John Alarcon and was originally published on CodePotent.com. The original post can be found here.

About John Alarcon

John Alarcon is a prolific creator of things. In late 2018, his attention turned to ClassicPress and, with more than a decade of WP experience already under his belt, he immediately began releasing plugins, articles, and tutorials created specifically for ClassicPress, solidifying his commitment to the project and establishing a role as a respected leader in the space. You can find John all over the web under the name "Code Potent".

View all posts by John Alarcon | Website