I’ve been working on upgrading one of my WordPress plugins – Search & Filter for some time now, quite the overhaul you might say\u2026<\/p>\n\n\n\n
When planning this update there were a bunch of things I knew<\/em> I needed to implement. I won’t bore you with all the details, but two tasks I wanted to tick off were:<\/p>\n\n\n\n The plugin is getting quite big, and having everything as a class with a unique name was getting a bit messy.<\/p>\n\n\n\n PHP namespaces solve this issue perfectly as you can scope your classes and then you only need to worry about the uniqueness of your top-level namespace (uniqueness is important in WP plugins in order to avoid conflicts with other plugins).<\/p>\n\n\n\n This also lends itself very nicely to consistent project structure because you will likely nest your files in directories matching your namespaces – everything becomes more predictable and uniform.<\/p>\n\n\n\n When PHP applications grow in size, rather than having to As long as your application has a predictable structure (namespace and class names), you don’t need to specify which files to load because we can predict where the relevant file is for a particular class (more on that later).<\/p>\n\n\n\n What’s also great about autoloaders is they only load files at the last minute – when a class is used – giving your application a lighter memory footprint.<\/p>\n\n\n\n These two concepts absolutely go hand in hand.<\/em><\/p>\n\n\n\n Ok, so we know from the above that if our plugin is going to grow that we’re going to want to use both namespaces and an autoloader.<\/p>\n\n\n\n And if we’re good developers, we also want to follow the WordPress coding standards<\/a>.<\/p>\n\n\n\n Coding standards are a good thing and often in the life of a developer, we’ll find conflicting scenarios where we might want to use one set of standards or the other.<\/p>\n\n\n\n The problem here is, while WordPress coding standards<\/a> cover a lot they don’t mention anything about namespaces.<\/p>\n\n\n\n I’ve read a few articles similar to this on ways to use autoloading with WordPress like this one<\/a> and this one<\/a> – and I’m going to share my take on a possible setup.<\/p>\n\n\n\n There is no mention of namespaces in the docs which leaves this wide open to interpretation and using our best guess – this post is my best guess as to what I think the WordPress way could be.<\/p>\n\n\n\n In the naming conventions<\/a>, it’s stated that class names should be cased like this:<\/p>\n\n\n\n And that they should have a corresponding filename something like this:<\/p>\n\n\n\n The class name is lowercased, underscores are hyphenated and the filename is prepended with So far so good.<\/em><\/p>\n\n\n\n There is a section in the best practises<\/a> which is hugely important:<\/p>\n\n\n\n Prefix everything!<\/p><\/blockquote>\n\n\n\n When a site can have hundreds of plugins, the only way our code won’t be messed with is if we prefix everything (including class names).<\/p>\n\n\n\n You might want to go with a simple abbreviation prefix, eg, if your plugin was called It’s already getting ugly, but it is necessary.<\/em><\/p>\n\n\n\n This would ideally be in a file:<\/p>\n\n\n\n When structuring a plugin like this it is common to find yourself with tons of files starting with If we switch to namespaces we can alleviate some of this pain and repetition:<\/p>\n\n\n\n The great thing here is, now This is how we would use the class now:<\/p>\n\n\n\n So I think there is not much complexity in this process – just start using them and drop the plugin prefix from all your class names (and filenames) – to be honest I think it’s keeping in line with the spirit of prefix everything<\/strong>.<\/p>\n\n\n\n *Also – I haven’t mentioned it explicitly – in my opinion, the naming convention of the namespace should match that of a class, with underscores separating words with initial capital letters.<\/p>\n\n\n\n A quick note about namespaces<\/strong> – they support nesting! So you can keep adding names spaces and sub-levels to improve your code organisation – eg:<\/p>\n\n\n\n Now we’ve got the namespace out of the way let’s head back to the autoloader.<\/p>\n\n\n\n There are a few ways to setup autoloaders (each with its own unique benefits) which I’m not going to get into right now<\/em> – I’m going to go for the easiest and most straightforward method while also keeping things in the spirit of the WordPress coding standards.<\/p>\n\n\n\n Setting one up requires using built-in PHP features<\/a>.<\/p>\n\n\n\n To implement this in a plugin would require adding some code at the top of your plugins main If we add the first example from the PHP docs:<\/p>\n\n\n\n Then we’ll be all set to go! Well, kind of.<\/p>\n\n\n\n What this code does is register a callback to be used, to specify which filename\/path we should look in order to find a class.<\/p>\n\n\n\n Roughly how it works:<\/strong><\/p>\n\n\n\n When a class is first used, eg: It is passed in the Also, something worth observing, when a class is used in a namespace, the full namespace + class name is passed through So let’s apply the coding standards to the autoloader and calculate the correct file path based on namespace and class name.<\/p>\n\n\n\n What we want to achieve:<\/p>\n\n\n\n And we’re going to convert namespaces. Classes belonging to a namespace should live in a folder (namespace name) that follows the conversion process of a class. So we need to add:<\/p>\n\n\n\n In addition – because the root plugin folder “is the plugin” and already has a directory name relevant to the plugin name, eg – So our plugin structure would look like this:<\/p>\n\n\n\n The class For me, this is the perfect balance of adding namespaces to WordPress plugins while keeping in the spirit of the coding standards.<\/p>\n\n\n\n To parse the name space and class names, and follow those above conversion rules (class name -> path + filename) would result in some PHP code like this:<\/p>\n\n\n\n I’ve also setup a tiny demo plugin using the above for you to play with over on GitHub:PHP namespaces<\/h2>\n\n\n\n
PHP autoloader<\/h2>\n\n\n\n
require<\/code> every other .php<\/code> file in a long list (or by some other method) it’s good practice to automatically load them.<\/p>\n\n\n\nWordPress enters the room\u2026<\/h2>\n\n\n\n
WordPress PHP Coding Standards<\/h2>\n\n\n\n
My_Class<\/pre>\n\n\n\n
class-my-class.php<\/pre>\n\n\n\n
class-<\/code>.<\/p>\n\n\n\nPlugin Development Best Practises<\/h3>\n\n\n\n
Speed Up<\/code>, you could use SU_My_Class<\/code> but in my opinion (and in the examples) the full name is better, so in theory, the ideal class name would be:<\/p>\n\n\n\nSpeed_Up_My_Class<\/pre>\n\n\n\n
class-speed-up-my-class.php<\/pre>\n\n\n\n
Switching to namespaces<\/h2>\n\n\n\n
class-speed-up-... .php<\/code> – to me it’s ugly, but it’s necessary because it accurately represents the class name, which has been prefixed too Speed_Up_...<\/code><\/p>\n\n\n\nnamespace Speed_Up;\n\nclass My_Class {\n\n}<\/pre>\n\n\n\nMy_Class<\/code> lives inside the Speed_Up<\/code> namespace, we don’t need to worry about prefixing it with Speed_Up<\/code> again. By using a namespace, we’ve kind of prefixed everything inside of it automatically and it won’t conflict with other plugins.<\/p>\n\n\n\n$my_class = new \\Speed_Up\\My_Class;<\/pre>\n\n\n\n
Speed_Up\\Frontend\\Scripts\\Register<\/pre>\n\n\n\n
Setting up the autoloader<\/h2>\n\n\n\n
php<\/code> file – if we’re sticking with the name speed-up<\/code> then it would be located:<\/p>\n\n\n\nwp-content\/plugins\/speed-up\/speed-up.php<\/pre>\n\n\n\n
autoload.php<\/code> in the root directory to store our autoloader – which is something you’ll probably see quite often when reading up on the subject. *<\/li><\/ul>\n\n\n\nspl_autoload_register(function ($class_name) {\n include $class_name . '.php';\n});<\/pre>\n\n\n\n$my_class = new My_Class()<\/code> and it is not yet loaded, the function we passed to spl_autoload_register<\/code> will be run to try to resolve the filename for the class.<\/p>\n\n\n\n$class_name<\/code>, and then you can see the file is loaded via include<\/code>. In the example above, based on the class name the file<\/p>\n\n\n\nMy_Class.php<\/code> would attempt to be loaded.<\/p>\n\n\n\n$class_name<\/code>.<\/p>\n\n\n\nWriting an autoloader for a WordPress plugin<\/h3>\n\n\n\n
class-<\/code>\u2026<\/li>\\<\/code> to a directory<\/li><\/ul>\n\n\n\nspeed-up<\/code> we shouldn’t create another folder called speed-up<\/code> just to match our Speed_Up<\/code> plugin namespace, it’s unnecessarily repetitive and we’ll actually remove that, and instead, we’ll create a folder called includes<\/code> for our classes instead.<\/p>\n\n\n\nspeed-up \/\/ top-level plugin folder\n-- speed-up.php \/\/ main plugin file\n-- readme.txt \/\/ required with every plugin\n-- includes \/\/ this folder is where we store all our classes\n---- database \/\/ folder for the sub namespace Database\n------ class-connect.php \/\/ class Connect\n class-worker.php \/\/ class Worker<\/pre>\n\n\n\n
Worker<\/code> in includes\\database\\class-worker.php<\/code> above would be accessed like this:<\/p>\n\n\n\nSpeed_Up\\Database\\Worker<\/pre>\n\n\n\n
The code<\/h3>\n\n\n\n
\/\/ Define the main autoloader\nspl_autoload_register( 'speed_up_autoloader' );\nfunction speed_up_autoloader( $class_name ) {\n\n \/\/ These should be changed for your particular plugin requirements\n $parent_namespace = 'Speed_Up';\n $classes_subfolder = 'includes';\n\n if ( false !== strpos( $class_name, $parent_namespace ) ) {\n $classes_dir = realpath( plugin_dir_path( __FILE__ ) ) . DIRECTORY_SEPARATOR . $classes_subfolder . DIRECTORY_SEPARATOR;\n\n \/\/ Project namespace\n $project_namespace = $parent_namespace . '\\\\';\n $length = strlen( $project_namespace );\n\n \/\/ Remove top-level namespace (that is the current dir)\n $class_file = substr( $class_name, $length );\n \/\/ Swap underscores for dashes and lowercase\n $class_file = str_replace( '_', '-', strtolower( $class_file ) );\n\n \/\/ Prepend `class-` to the filename (last class part)\n $class_parts = explode( '\\\\', $class_file );\n $last_index = count( $class_parts ) - 1;\n $class_parts[ $last_index ] = 'class-' . $class_parts[ $last_index ];\n\n \/\/ Join everything back together and add the file extension\n $class_file = implode( DIRECTORY_SEPARATOR, $class_parts ) . '.php';\n $location = $classes_dir . $class_file;\n\n if ( ! is_file( $location ) ) {\n return;\n }\n\n require_once $location;\n }\n}<\/pre>\n\n\n\n
Github Repo<\/a><\/p>\n\n\n\n