PHP Class Loading and WordPress Plugins

/ PHP, Wordpress / by Paul Robinson / 4 Comments
This post was published back on January 27, 2019 and may be outdated. Please use caution when following older tutorials or using older code. After reading be sure to check for newer procedures or updates to code.

WordPress plugin development can be an absolute pain.

That’s right. I said it. Coding plugins for clients and keeping that code neat and tidy can be a nightmare.

The best way to write your code (in most cases) to prevent conflicts and keep code together is to use classes.

Obviously you should use your best judgement as to if the plugin needs to use classes. Sometimes for simple code a prefixed function and a hook will work just fine.

The problem comes when you need multiple classes to separate your code. What is the best way to load your classes? That depends. Let’s take a look at some of the ways you can load classes.

Standard Include

The simplest way to make a class available. Just include or require the file. You can then instance your class or use any static functions.

Returned Include

Another method is to instance your class and return it. For example in My_Awesome_Class.php you may have the following:

This might look a little unusual if you haven’t seen it before. The return keyword can be used in a file. When that file is included whatever was returned will be provided. For example:

This can be somewhat helpful to provide an easy way for other developers to access classes in your plugin. For example:

Using this method other developers can access your main plugin class and all it’s sub-classes via the variable you have provided.

Using require_once or include_once again will not return another instance of your class. It will return a boolean. To make another instance simply new your class into a variable as normal.

SPL Autoload

My favorite method of loading classes is to use PHP’s built in spl_autoload_register() function.

If you are unfamiliar with spl_autoload_register() it allows you to define a function that will load your class when you try to use it. That is regardless of if you are trying to call a static method or instance a class.

This is just one way I’ve used autoloading in the past. The function you pass to spl_autoload_register() will receive the name of the class being called.

Your function should take the name and try to load the relevant file. This is one of the reasons it is good to stick with a naming convention for your classes.

In this case the autoload function checks the requested class has our project prefix (MAP) and if the file actually exists. Files that contain classes are named in the same way as the class itself. So My_Awesome_Class would be held in a file called My_Awesome_Class.php.

That’s all there is to it. Now if you try to instance a class or use a static method from any classes PHP will try to automatically include the file for you.

Remember to instance your main plugin class so your autoloader function is used. Also remember you will still receive an error if you try to use a class that can’t be autoloaded.

You can also define multiple autoloaders. For example, if you are using the awesome CMB2 in your WordPress plugin they also use SPL autoloading. PHP will just run each autoloader in turn.

Even more good news when using the SPL autoloader. It does not cause any problems with using Composer’s autoloader.

Wrapping Up

In this post we’ve looked at how you can load classes in a WordPress plugin, and with PHP in general.

Which method you would use is entirely up to which suits your project. There are other methods such as using PSR4 autoloading via Composer, that method would require the use of Namespaces and is something outside the scope of this article.


Author’s gravatar

So if you call require_once multiple times with the same file, it’ll return a new instance every time??

Author’s gravatar author

Hi Manny,

No. Any following requires of the same file will produce a boolean with the value true as noted in the PHP documentation. I’ll edit the article to mention this as after a quick search I hadn’t realized how many questions on sites like Stack Overflow there were on require and include

This is why it is a matter of choice as to which method is best for your project. If you are going to be creating multiple instances it is better to either simply require/include the file and instance to a variable or use the SPL autoloader if there are going to be a lot of classes to load.

Author’s gravatar

A tangent by mind is still reeling that you can use return in an included file:

I’m assuming it would be possible to return out of an included file early, like you would a function if your condition was already met/not met/etc. Real world example is I was helping with a WordPress plugin where the author wrapped classes in if statements to prevent collisions if the class was accidentally included in another plugin ie if( !class_exists($classname) ) {/*define class here */}. Wouldn’t it make sense you could do if( class_exists($classname) ) { return; } to the same effect?

Author’s gravatar author

Hi Manny,

Yes, you could technically use return to exit the script if the class already exists. I can’t see any reason why it would be bad to do so, but I believe it is considered best practice to enclose the class in the class existence check.

Just remember to be careful of using return incorrectly, as noted by the PHP docs:

return returns program control to the calling module. Execution resumes at the expression following the called module’s invocation.

Meaning you should always use exit(), die() or in the context of WordPress wp_die() if you need to end all code execution. I’ve seen many examples of this used incorrectly so I wanted to make sure I mentioned it.

Older Comments
Newer Comments

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

I'll keep your WordPress site up-to-date and working to its best.

Find out more