DEV Community: Ross Morsali

Using PHP namespaces in WordPress plugins + creating an autoloader

Ross Morsali — Thu, 19 Aug 2021 10:28:44 +0000

I've been working on upgrading one of my WordPress plugins - Search & Filter for some time now, quite the overhaul you might say...

When planning this update there were a bunch of things I knew I needed to implement. I won't bore you with all the details, but two tasks I wanted to tick off were:

Use PHP namespaces
Setup an autoloader

PHP namespaces

The plugin is getting quite big, and having everything as a class with a unique name was getting a bit messy.

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).

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.

PHP autoloader

When PHP applications grow in size, rather than having to require every other .php file in a long list (or by some other method) it's good practice to automatically load them.

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).

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.

These two concepts absolutely go hand in hand.

WordPress enters chat...

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.

And if we're good developers, we also want to follow the WordPress coding standards.

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.

~~The problem here is, while WordPress coding standards cover a lot they don't mention anything about namespaces.~~

2023 Correction: Looks like a section on namespaces has now been created and that they follow the same convention described in this post.

WordPress PHP Coding Standards

In the naming conventions, it's stated that class names should be cased like this:

My_Class

And that they should have a corresponding filename something like this:

class-my-class.php

The class name is lowercased, underscores are hyphenated and the filename is prepended with class-.

So far so good.

Plugin Development Best Practises

There is a section in the best practises which is hugely important:

Prefix everything!

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).

You might want to go with a simple abbreviation prefix, eg, if your plugin was called Speed Up, you could use SU_My_Class but in my opinion (and in the examples) the full name is better, so in theory, the ideal class name would be:

Speed_Up_My_Class

It's already getting cumbersome, but it is necessary.

This would ideally be in a file:

class-speed-up-my-class.php

Switching to namespaces

When structuring a plugin like this it is common to find yourself with tons of files starting with class-speed-up-... .php - to me it's not particularly elegant, but it's necessary because it accurately represents the class name, which has been prefixed too Speed_Up_...

If we switch to namespaces we can alleviate some of this pain and repetition:

namespace Speed_Up;

class My_Class {

}

The great thing here is, now My_Class lives inside the Speed_Up namespace, we don't need to worry about prefixing it with Speed_Up again. By using a namespace, we've kind of prefixed everything inside of it automatically and it won't conflict with other plugins.

This is how we would use the class now:

$my_class = new \Speed_Up\My_Class;

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.

2023 Update: WordPress coding standards now recommends this as the way to use namespaces.

A quick note about namespaces - they support nesting! So you can keep adding names spaces and sub-levels to improve your code organisation - eg:

Speed_Up\Frontend\Scripts\Register

Setting up the autoloader

Now we've got the namespace out of the way let's head back to the autoloader.

There are a few ways to setup autoloaders (each with its own unique benefits) which I'm not going to get into right now - I'm going to go for the easiest and most straightforward method while also keeping things in the spirit of the WordPress coding standards.

Setting one up requires using built-in PHP features.

To implement this in a plugin would require adding some code at the top of your plugins main php file - if we're sticking with the name speed-up then it would be located:

wp-content/plugins/speed-up/speed-up.php

We could also create a new file autoload.php in the root directory to store our autoloader - which is something you'll probably see quite often when reading up on the subject. *

If we add the first example from the PHP docs:

spl_autoload_register(function ($class_name) {
    include $class_name . '.php';
});

Then we'll be all set to go! Well, kind of.

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.

Roughly how it works:

When a class is first used, eg: $my_class = new My_Class() and it is not yet loaded, the function we passed to spl_autoload_register will be run to try to resolve the filename for the class.

It is passed in the $class_name, and then you can see the file is loaded via include. In the example above, based on the class name the file

My_Class.php would attempt to be loaded.

Also, something worth observing, when a class is used in a namespace, the full namespace + class name is passed through $class_name.

Writing an autoloader for a WordPress plugin

So let's apply the coding standards to the autoloader and calculate the correct file path based on namespace and class name.

What we want to achieve:

Class filenames must be prefixed with class-...
Class filenames should be lowercase
Underscores should be replaced with dashes

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:

Namespace names will be converted to lowercase
Namespace names will have underscores replaced with dashes
Namespaces will be folders so convert \ to a directory path

In addition - because the root plugin folder "is the plugin" and already has a directory name relevant to the plugin name, eg - speed-up we shouldn't create another folder called speed-up just to match our Speed_Up plugin namespace, it's unnecessarily repetitive and we'll actually remove that, and instead, we'll create a folder called includes for our classes instead.

So our plugin structure would look like this:

speed-up // top-level plugin folder
-- speed-up.php // main plugin file
-- readme.txt // required with every plugin
-- includes // this folder is where we store all our classes
---- database // folder for the sub namespace Database
------ class-connect.php // class Connect
       class-worker.php // class Worker

The class Worker in includes\database\class-worker.php above would be accessed like this:

Speed_Up\Database\Worker

For me, this is the perfect balance of adding namespaces to WordPress plugins while keeping in the spirit of the coding standards.

The code

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:

// Define the main autoloader
spl_autoload_register( 'speed_up_autoloader' );
function speed_up_autoloader( $class_name ) {

    // These should be changed for your particular plugin requirements
    $parent_namespace = 'Speed_Up';
    $classes_subfolder = 'includes';

    if ( false !== strpos( $class_name, $parent_namespace ) ) {
        $classes_dir = realpath( plugin_dir_path( __FILE__ ) ) . DIRECTORY_SEPARATOR . $classes_subfolder . DIRECTORY_SEPARATOR;

        // Project namespace
        $project_namespace = $parent_namespace . '\\';
        $length = strlen( $project_namespace );

        // Remove top-level namespace (that is the current dir)
        $class_file = substr( $class_name, $length );
        // Swap underscores for dashes and lowercase
        $class_file = str_replace( '_', '-', strtolower( $class_file ) );

        // Prepend `class-` to the filename (last class part)
        $class_parts = explode( '\\', $class_file );
        $last_index = count( $class_parts ) - 1;
        $class_parts[ $last_index ] = 'class-' . $class_parts[ $last_index ];

        // Join everything back together and add the file extension
        $class_file = implode( DIRECTORY_SEPARATOR, $class_parts ) . '.php';
        $location = $classes_dir . $class_file;

        if ( ! is_file( $location ) ) {
            return;
        }

        require_once $location;
    }
}

I've also setup a tiny demo plugin using the above for you to play with over on GitHub:

Github Repo

Are you doing it a different way? No technique is perfect and there is always room for improvement - let me know your thoughts!

If you want to read more articles like this you can follow me on Twitter to keep up to date.

How to create a (multiple) block plugin for WordPress

Ross Morsali — Sun, 08 Aug 2021 09:56:44 +0000

Photo by Elodie Oudot on Unsplash

Want the files?
If you're impatient like me, you can go straight for the code on GitHub.

Creating a single block plugin

There's already a great package out there for creating a single block plugin, so we're going to use that as the foundation for creating our multiple block plugin.

Since the release of the @wordpress/create-block package, creating a block plugin with an an awesome development setup (scaffolding) has gotten a lot easier - it takes a lot of the hard work out of setting up webpack, a transpiler, scss + a whole lot more - although I'm sure some of you would still rather roll your own.

If you want to get going quickly I recommend getting familiar - and this post assumes you already know how to use @wordpress/create-block, but we'll still go through the steps from the beginning.

Anyway, I saw a question recently (I think on Twitter) - something like, "How can I create multiple blocks with this tool"?

So I've been digging into this and that's what I aim to share in this post.

Setting up `@wordpress/create-block`

I'll try to be brief on this, but you can follow the link above for a more in depth setup guide.

Lets start by creating a new plugin using @wordpress/create-block.

In a local development environment, locate your /wp-content/plugins/ directory and open a terminal from there, then enter:



npx @wordpress/create-block multiple-blocks-plugin

It can take some time to setup, grab a drink...

This creates the main plugin directory with the name multiple-blocks-plugin and the default project structure. Enter this directory and start the dev script:



cd multiple-blocks-plugin
npm run start

Now the plugin is ready to use and it can be enabled via the plugins page in your WordPress dashboard.

Once enabled, verify that setup has gone well by adding the block via the post editor - it will be called Multiple Blocks Plugin:

Existing structure

Assuming the above went well, we can now take a look at the project structure, and visualise how this needs to be re-arranged in order to support multiple blocks.

I won't be explaining all the files / folders, just the relevant ones.

`multiple-blocks-plugin.php`

This is the main plugin file, and it's incredibly simple - it calls register_block_type() with the current directory as an argument, which then tries to locate a block.json file (and registers it).

`block.json`

This is the main configuration file for your block, where you define basic settings - it also includes references to the other files that are used with your block (the editor script, editor style and shared style).

`src`

The src directory is where you'll be doing most of the work on your block. This is the place you'll usually add your block editor functionality as well as your styles.

`build`

We're using a modern development stack - which means we can write ESNext and JSX code in our project, but before it can be used on all browsers it must be converted (transpiled). This process is handled automatically and the result is placed in this directory.

`package.json`

Amongst other things, this file contains the npm run start script used to build your block, we'll be updating this and adding scripts for each block you want to create.

Convert into a multiple blocks plugin

So now let's begin the process of transforming the existing structure, into a structure that supports multiple blocks.

The main thing to note here is, block.json, src, and build all belong to the "block", whereas all the other files in the project are related to the plugin / development setup.

0. Create a directory to house all blocks

Let's name this something imaginative, like... blocks:
multiple-blocks-plugin/blocks/

The next steps can be repeated for every new block you want to create.

1. Create a directory for the block

In this case we'll use buy-button:
multiple-blocks-plugin/blocks/buy-button/

2. Identify & copy the block related files

We can move (if it's the first time doing this, otherwise copy) block.json, src and build in to the new block directory.

Your directory structure should look something like this:

3. Rename block settings in block.json

This step is important, we need to update the block name and title to something unique. These are the two properties to change:



"name": "multiple-blocks-plugin/buy-button",
"title": "Buy Button",

Take a note of the new name - multiple-blocks-plugin/buy-button - we'll be needing it in the next step.

4. Update reference to the new block name

In your blocks src directory, edit index.js:
multiple-blocks-plugin/buy-button/src/index.js

and modify the line containing registerBlockType()

Lets update the name to use our new name (from the last step):



registerBlockType( 'multiple-blocks-plugin/buy-button', {

5. Update CSS classes

There are two SCSS files to locate:

blocks/buy-button/src/style.scss
blocks/buy-button/src/editor.scss

They both contain the class:



.wp-block-create-block-multiple-blocks-plugin

However the class name is based on our block name and should be changed to:



.wp-block-multiple-blocks-plugin-buy-button

6. Update `multiple-blocks-plugin.php` to reference the new location

Here we simply want to change the directory used in register_block_type (if it's the first time doing this) or add an additional register_block_type to reference our new block directory.

We can update the main function like this:



function create_block_multiple_blocks_plugin_block_init() {
    register_block_type( plugin_dir_path( __FILE__ ) . 'blocks/buy-button/' );

    // Additional blocks would be registered here
    // register_block_type( plugin_dir_path( __FILE__ ) . 'blocks/another-block/' );
}

7. Create scripts for your new block in `package.json`

When we use npm run start we're running a script defined in package.json, using some default settings.

Because we moved our block files, we'll need to create scripts to build them in their new locations. In the scripts section of package.json you'll need to add:



"start:buy-button": "wp-scripts start blocks/buy-button/src/index.js --output-path=blocks/buy-button/build/",
"build:buy-button": "wp-scripts build blocks/buy-button/src/index.js --output-path=blocks/buy-button/build/"

Notice that we specified an input path pointing to the src directory of our block, and output path pointing the build directory of our block, and that we updated the scripts by adding our block name :buy-button to the script name.

With the above addition, this is the new way to start your dev build (from the command line):



npm run start:buy-button

You'll need to use that instead of just npm run start for running in development mode and for production you can use:



npm run build:buy-button

And that's it, you're good to go - what you do with these blocks is up to you!

Summary

So the first run through, we essentially moved the default generated block files, into a sub-directory and re-wired the project to use the new name + location.

For each new block you want to create, the process will be similar, just follow steps 1 - 7. All you need to do is copy the default block files over (from an existing project, or grab a fresh copy from @wordpress/create-block) -

Note: the build folder is in fact not necessary (although we moved it earlier) - it is automatically generated when you run the command line scripts.

Repo + files

The project is ready to be used and comes with 2 blocks - Buy Button and Hero Block (they don't do anything though) - but I do recommend learning the above process and creating additional blocks yourself.

Download from GitHub

Questions + feedback are most welcome.

If you liked this post, come and say hi over on Twitter - my plan is to create more WordPress developer related content in the near future.