On Goals and Intentions

This morning, I sat down at the kitchen island and drafted up some notes of reflection. I’ve thought a lot about how I’ve spent my creative focus during previous decades (drawing, playing music, learning computer programming), and the various ways I’ve chosen to pass the time: video games, board games, listening to records, watching movies, etc.

Awhile ago, I made a conscious decision to set the focus for this blog to be about topics pertaining to my professional career. In some ways, that’s been great, because focus in in part what I require. In others, it’s left me feeling like I haven’t given myself a true outlet to talk about dreams and goals that may not have much bearing on my professional self, but which carry a lot of weight around who I am and what I want out of this life. I don’t write enough from either perspective to bother making the distinction, so for today at least, it makes sense to just jot down what I feel for the purpose of writing at all.

I had a great conversation with my friend Michelle last week about goal-setting. I mentioned how it was mid-January, and I hadn’t yet written any posts to reflect upon my goals from last year. I felt in some ways that I’d accomplished a lot in 2019, but that things quickly got off course in June after I started leading a huge client project at work and signed up to give more and more unique presentations at WordCamps and internal continuous education sessions.

Michelle told me that she prefers not to set goals, but that instead, she likes to set intentions that can help guide her focus and behavior for a given period of time. It really struck me as a better way to go about things. On the one hand, setting and achieving a measurable goal gives you great information about your quantitative progress over a span of time. “I set out to read 12 books, and I did it!” On the other, it exposes to you a number of serious shortcomings: your inability to plan, to adapt to changing conditions, to be realistic about what you can actually achieve.

Mostly, it leaves you feeling bad, either because you didn’t accomplish the thing that you set out to do, or maybe because you did accomplish it and hated every minute of working toward something you don’t actually care about.

Here’s a truly dumb, real-life example from last year: I wanted complete the 10×10 challenge, something the board gaming community labels as playing ten games ten times each. And I did it (a real achievement, obviously)! Ultimately, though, I disliked everything about it, particularly as the year-end got closer and closer, and I had a dedicated list of games that I needed to keep playing, regardless of whether I actually wanted to.

And, while I think that’s not a very meaningful example, I think it can be applied to other goals we beat ourselves up over. For instance, I set out to apply to one out of town WordCamp. I applied to four WordCamps total last year – three of them out-of-town – and was accepted to three. Goal accomplished! The problem is that I think I was so eager to prove to myself that I could do it, that I didn’t necessarily consider the ramifications of it all: the time it takes to prepare a talk, the time and expense of travel, the focus it can take away from other parts of your life. I had a wonderful time speaking at each of these conferences and, in hindsight, was really glad that I did it. But, at the end of the day, I don’t know that it furthered my own vision for whatever it is I’m setting out to achieve with my career or that it brought me closer to self-actualization of any sort. It was a thing that I arbitrarily set out to do, I did it, and now what?

Intent, however, is different, though it of course has its own sets of trade-offs. Let’s presume one of my intentions for this year is to perform more acts of kindness. How do I measure it? How will I know I’ve done it at the end of the year? Shouldn’t I instead set a goal of sending, say, ten thank you cards by December, or purchase five random gifts?

The distinction in my mind centers on how reflecting on the goal or intention happens. If the goal is to send ten thank you cards over the course of a year, you might revisit that goal every couple of months to see how your progress has gone, and realize that you’re either far behind on your goal (“I better send more thank you cards!”), or you’re far enough ahead that you can relax for awhile (“I already sent eight thank you cards! I can coast for a bit…”). Intention, however, can serve as more of a guiding principle (“Anytime someone invites me over for dinner, I want to follow up by sending a handwritten note.”). It accommodates for failure without needing to beat yourself up too much over that failure. It’s measurable in that you can still take stock in how well you adhered to that intention and, perhaps, whether it converted from intention to habit (“I intended to send thank you cards frequently, and now I do it all the time.”).

Perhaps this isn’t an ideal example, but it makes sense in my head, and that’s really all that matters, right? :)

What Are My Intentions?

This is the part upon which I’m still processing, and also where I’m probably also giving in to the normal focus of this blog. That said, I do want to comment a bit about the last year with the purpose of trying to think through this all out loud a bit.

First, something that I didn’t explicitly set as a goal in my post last year but that I’ve been working toward is enhancing my online privacy and either taking ownership of or redistributing management of my data. In 2019, I completed every step of the Online Security Checklist, which funnily is 90% “leave Google”, but that’s what I did. I canceled my Google G-Suite account and stopped using Gmail, Google Calendar (much to my partner’s dismay), and Google Maps. I closed my Dropbox account, because I feel the service they provide is encroaching beyond what I signed up for. I switched to Firefox, and use DuckDuckGo as my primary search engine. I use Apple Maps now which, although Apple has plenty of their own privacy concerns, I’m okay with because it’s not all about leaving one big service for another, but rather, no longer consolidating all of my eggs in one basket.

I also bought a Linux desktop, with the long-term intention of switching to Linux for work, too, if I find that I can work within that ecosystem. It’s a huge shift for me, but I’m enjoying the challenge of learning how to work in a new environment, just like I did when I switched from Windows to a Mac.

Second, I intend to slow down. I struggle a lot with indecision, in part because there are so many things I want to do that I wind up doing nothing at all. For instance, I’ve been wanting to write this blog post all week, but I’ve also wanted to get familiar with this new computer, help my friend upgrade his WordPress site, read a book, play some video games, play some board games, follow the historic news of the week, engage with the community, write e-mails to friends and family, attend bar trivia with my partner, go see the new Star Wars (I still haven’t), do my laundry… the list goes on and on. I need to learn to accept that I can’t do everything that I want to do. Instead, what I can do is dedicate my focus toward achieving something particular on a given day, and start there. Today, I want to publish this blog post and go spend time with my friends and share in the pride of seeing their teenage nephew play a show at a local rock club (I remember my first rock club show!).

In other words, I can be aware of all the things I want to do and make incremental progress toward doing them by setting a focus for the day. Checklists are great – my partner uses them all the time.

Third, I intend to write more. Not necessarily on this site, but I think taking account of how I’ve spent my time each day will give me a better sense of whether I’m on the right path. I’ve read stories from friends who have kept gratitude journals, and I think that’s one excellent way to take stock. It’s so easy to get caught up in the day-to-day that it’s easy to lose sight of the big picture, but writing it down helps bring guidance and clarity. It’s a good reminder to myself, too, that not everything needs to be for public consumption. Sometimes just writing something down for the sake of relection brings about some level-setting and accountability.

Lastly, I intend to be more present. That means getting out of the house more, showing up for events, supporting my friends, and engaging in more conversations. It means putting the damn phone away. It might mean volunteering. I closed up shop when things got too demanding for me last year, and escaped into board games and screen time. It resulted in less investment in personal projects, less reaching out to make plans, less involvement in my community, and I’ve abhorred every minute of it (I mean, almost… I do love board games). I like talking to people, making friends, learning how to solve problems, and being helpful where I can. I don’t want to close myself off to potential friendships and new experiences just because I’m tired from a long day or things aren’t going just quite right at any particular moment. It’s important to set this intention and follow through as much as possible, because presence is supportive, and being supportive leads to all sorts of opportunities.

I’m grateful for my friendships, online acquaintances, and colleagues who helped pave the way for where I am today. This year, I intend to return the favor.

A Quick Developer’s Guide to the WordPress Block Editor

TL;DR: You can skip all the exposition below and click here to get to the good part.

If you’re anything like me, you’re interested in the ever-changing landscape of web development, but your day-to-day work precludes you from digging too deeply into a topic during working hours unless a project necessitates it. As such, most of your study time happens during nights and weekends, either via focused study, exploratory projects, or a combination of the two. You might also happen to be interested in a lot of different topics, so the investment of digging into and not only acquiring but also retaining that knowledge is significant.

In the past year, I’ve spent some portion of time learning (or re-learning) the basics of Swift, Craft CMS, Laravel, React, Symfony Components (Console, Process, etc.), Bash, MySQL, NPM, converting XML to JSON… the list goes on and on. In some cases, I have a working app; in others, an unfinished idea. In most cases, though, my trials are loose collections of notes and throwaway code to try and understand various concepts, or to play around with a reusable approach to solving a problem even while I’m trying to understand the concepts behind the solution.

The WordPress Block Editor, released into core with version 5.0 in December of last year, has been one such challenge. I defined learning how to create custom blocks as a goal of mine in 2019, and tinkered with some reusable approaches to it early in the year. Still, most of my work this year has been related to developing back-end solutions, be they custom migrations, supporting existing architectures, or establishing approaches to object-oriented plugin development. My evenings and weekends had left time for tinkering, but most often, I was either preparing or rehearsing a presentation, spending time with friends and family, or just trying to unwind from a challenging day’s work.

To that latter point, this summer, I started working as a lead on a big project at WDS that fully incorporates the block editor into a publishing workflow. In the long term, this means I’ll have far more opportunities to work with the block editor, but shorter-term, it has meant integrating work that already exists and, as a project lead, doing more planning and strategy than actual development.

But I digress…

During the first weekend in November, I attended WordCamp US in St. Louis, MO. I sat in on some beginner sessions and workshops about the block editor to refresh and verify the knowledge I already have, and I chatted at length with one of my colleagues about his interest in JavaScript development and in the block editor in particular. It was a fun and exciting trip, capped off via a two-day summit with my client and their agency partners about our plans for the next six months.

Upon returning from St. Louis, I had a nice, long 6-day weekend in which to relax, refresh, and start digging into the block editor in earnest. My “quick start” guide follows.

What You Should Know About the Block Editor

Over the weekend, I watched Zac Gordon‘s excellent Gutenberg Block Development Course, and it helped to clear up a lot of questions that I had as a PHP developer who is trying to better understand the JavaScript ecosystem and how to work with the block editor.

Above all else, there are two primary resources for getting started with creating custom blocks in WordPress: the Block Editor Handbook and the Gutenberg plugin repository. Both of those links have just about everything you could possibly want to know about creating blocks, but they serve better as reference materials than tutorials, and that, really, is the rationale behind this post.

Here are some key takeaways I’ve learned over the weekend that will hopefully help you on your journey in developing custom blocks in WordPress, particularly if you’re familiar with a more traditional PHP-based workflow:

  • The block editor is composed of a series of NPM packages. These packages correspond with what you’ll find in the packages directory of the Gutenberg plugin. This is one of the most important things to understand, particularly if you find it more helpful to look at code than README docs.
  • One of those packages is the block-library, which contains all of the editor blocks that are part of WordPress core. The Gutenberg plugin here is useful, because this gives you tangible examples for how each block is constructed. As a developer new to the block editor, you can use any of these examples as a starting point for your own custom block exploration.
  • The dependencies you define when you register a block correspond with other packages in the Gutenberg plugin, such as element (WordPress’s abstraction layer around React), editor (which includes components like RichText for input and BlockControls for concepts like alignment), and data (which serves as a sort of communication hub between the component and WordPress itself), among others.
  • Blocks can be registered via PHP or JavaScript, but most-typically, only dynamic blocks will be registered via PHP. PHP’s role in block registration is primarily limited to making WordPress aware of the main JavaScript and CSS files required to render and make a block functional.

None of this information above will walk you through creating your first blocks (unlike the tutorials in the Block Editor Handbook, which I think are fairly sufficient for early exploration), but I do feel strongly that these details will help new developers better understand how to use the various components available from within the block editor, and more importantly, which ones to set as a dependency of a block.

For instance, the Block Editor tutorial indicates that you can require the wp-editor package as a dependency for your block and use the RichText component from it to provide a rich text input. But, it falls just short of linking back to the Gutenberg repository to provide examples and further documentation for that particular component so that developers can fully understand what it is and how it ties in with the block they’re trying to create.

Hopefully, putting together some pieces of this puzzle will help you on your block editor journey. It’s been an important weekend for discovery for me. This type of exploration can only happen during trial and error, which is why a long weekend is ideal. In my situation, the ability to apply these learnings to client work is going to go a long way toward helping me understand how things are constructed, and I’m hopeful those of you reading this will be able to apply some of those takeaways as well.

Support for Composer Autoloading w/ Custom Fallback

Because it’s a part of my every day workflow, I spend a lot of time thinking about WordPress. And, because I think there are lots of ways that the WordPress codebase could improve from an architectural perspective, I also spend a lot of time paying attention to how other open-source PHP projects are structured. Lastly, because a lot of my day-to-day work involves custom plugin development for WordPress, I think about ways to make things better organized, more streamlined, and easier to follow along so that, when I come back to those projects months or years later, I can easily pick back up right where I left off.

There are a few things I find particularly interesting from a plugin development perspective, and those things are dependency management, plugin structure, plugin bootstrapping, and class autoloading.

I wrote a bit about how I like to approach plugin development a few months ago. At the time, I’d only really considered using Composer’s autoloader – if I was submitting a plugin to the WordPress repository or had plans to otherwise make that plugin available on sites that didn’t use a Composer-based install, my approach was to version control the vendor directory and ship it with the plugin.

In many cases, I still feel that using Composer’s autoloader is the best way to go, because it alleviates the need to write your own custom autoloader for every single project. That said, this week, I had a situation come up where I was forced to implement my own autoloader, and it gave me an idea. Let’s examine.

Here’s an example plugin bootstrap file:

<?php
/**
 * Plugin Name: WP Plugin Starter
 * Description: A boilerplate project to quickly scaffold up new WordPress plugins.
 * Author: Jeremy Ward
 * Author URI: https://jmichaelward.com
 * Version: 0.1.0
 *
 * @package JMichaelWard\WPPluginStarter
 */

namespace JMichaelWard\WPPluginStarter;

if ( ! class_exists( 'JMichaelWard\WPPluginStarter\Plugin' ) ) {
	try {
		require_once plugin_dir_path( __FILE__ ) . 'src/autoload.php';

		spl_autoload_register( __NAMESPACE__ . '\autoload' );
	} catch ( \Throwable $e ) {
		// @TODO Implement actual error handling.
		return;
	}
}

add_action( 'plugins_loaded', [ new Plugin(), 'run' ] );

This example plugin is shipping with a composer.json file that defines a PSR-4 style autoloader. In the bootstrap file, I run a check to see whether the main Plugin class exists at the plugin’s namespace. If it does, great! It’s likely the plugin was installed using Composer, and that the vendor/autoload.php file was required somewhere further upstream, either in wp-config.php or maybe via a loader file in an mu-plugin.

It’s what happens if the class file isn’t found is what I think is interesting. In that situation, we’ll try and require a fallback autoloader class from within the plugin itself, and set up our own autoloader. Here’s what mine looks like:

/**
 * Quick and dirty custom autoloader if the class files are not already available via Composer.
 *
 * This function ignores all non JMichaelWard\WPPluginStarter namespaced classes, then performs a require on the class
 * based on the PSR-4 standard. This presumes that the class file names match the name of the class itself, and
 * is following the directory structure as defined by the namespace.
 *
 * @param string $class_name Name of the class to autoload.
 *
 * @author Jeremy Ward <[email protected]>
 * @since  2019-10-12
 * @return void
 */
function autoload( $class_name ) {
	if ( false === strpos( $class_name, __NAMESPACE__ ) ) {
		return;
	}

	$parts     = explode( '\\', $class_name );
	$file_path = implode( DIRECTORY_SEPARATOR, array_splice( $parts, 2 ) );

	require_once trailingslashit( __DIR__ ) . $file_path . '.php';
}

This autoloader bails early if the class name passed into it doesn’t share the same namespace. Otherwise, it explodes the class name into an array – in this case, it would be JMichaelWard, WPPluginStarter, and Plugin – and then recreates the class file path after splicing out the first two values form the namespace, so we’re left with Plugin.php as the include.

In this situation, the autoload.php file is kept in the same src/ directory with the rest of our class files, so the autoloader’s path is relative to all of those classes.

Because we’re following the PSR-4 convention, which essentially maps file names to the directory structure, this means we can located classes in nested directories, such as JMichaelWard\WPPluginStarter\Content\ContentRegistrar.php, which would be stored in a Content directory within src/. As long as engineers follow the naming convention, classes will be discovered correctly and no errors will be thrown.

The benefit of this approach is that you can quickly scaffold up a plugin following a PSR-4 styled approach, and allow others to install it either by following a Composer-based process, or just by including it in their plugins directory. The downside, of course, is if there are any third-party dependencies – this approach won’t play nice, because you’d need to refactor the autoload.php file to check for namespaces that aren’t your own, and would have to engineer a way to locate those files.

That said, for a quick, lightweight, out-of-the-box solution, I think this one will meet a lot of needs.

You can view the full code for this example plugin on GitHub. I’m working on that repo to create a plugin starter that will ship with a Symfony Console command that will run on the composer create-project event. When installed as a new package, the console will trigger a wizard that will ask a series of questions in order to automatically update namespaces, author details, and more, so that developers can more quickly get to the focus of their project: making the plugin do whatever it needs to actually do. That’s still in progress, so look for another post in the coming weeks.

Upcoming Conferences

This is just a quick post to announce that I’ve been accepted to speak at a pair of upcoming conferences.

First, I’ll be giving a new talk, Lose Your Head! Re-imagining WordPress’s Role in Content Presentation at WordCamp Minneapolis-St. Paul. The conference is being held on August 22-24 at the McNamara Alumni Center on the University of Minnesota Campus, and my session is scheduled for first thing Saturday morning.

In September, I’m flying to California to take part in WordCamp Sacramento, where I’ll be doing a reprise of my presentation, Modernizing Your Development Workflow Using Composer. The schedule hasn’t yet been released, but the conference will be held on September 21-22 at The Falls Event Center in Roseville, CA.

Unfortunately, neither of my submissions were accepted at WordCamp US this year, but I’m looking forward to visiting St. Louis in November, catching up with some old friends, and hopefully making some new ones. If you’re planning on going, give me a shout so we can find some time to get together!

WordPress Plugin Bootstrap Files and Class Architecture

I’ve been casually working on my Board Game Collector plugin off and on for awhile. It’s a fairly basic plugin that registers a custom settings page, post type, and WP-CLI command that allows you to connect to the BoardGameGeek API to pull in data for a given user’s board game collection. I’m still undecided as to the long-term utility of the plugin, so when I work on it, it becomes a playground of sorts for me to try out ideas.

A couple of months ago, I completely refactored the plugin to take advantage of the OOPS-WP library I had written for WebDevStudios, because I wanted it to more closely follow the style I’d established over the years for WordPress projects. This morning, after revisiting it once more, I decided I didn’t fully like the structure of the plugin bootstrap file, so I made a few minor tweaks. I’ve never actually written my approach down anywhere, so I figured a rainy day like today was as good as any to talk about my coding philosophy when it comes to plugin bootstrap files and class file organization.

Anatomy of a Plugin Bootstrap File

First, let’s take a look at the plugin bootstrap file for the Board Game Collector plugin is it exists in the develop branch of the repository this morning:

The main thing to notice here is that I’ve established that the sole responsibility of the bootstrap file is to determine whether WordPress can locate the files it needs to run. Any further plugin behavior is delegated to the main plugin file where services are instantiated, hooks are registered, constants are defined, and so on. Since I’m using Composer for class autoloading, I do want WordPress to check whether that autoloader exists locally within the plugin in case I installed it directly instead of requiring it via composer install somewhere from within the WordPress project.

One thing I changed this morning was moving toward the use of a try/catch block when attempting to initialize the plugin class. Previously, I was running a class_exists check to determine whether or not the plugin can run. But, in working with some enterprise WordPress multisite projects, I’ve come to learn that – depending on the particular configuration – class_exists might return true for a plugin that is deactivated on one site but active on another. In those projects, we had circumvented that behavior by passing in false as the second parameter to class_exists, but I think this try/catch approach is more explicit. If the class files are not loaded, then my plugin will catch the error and handle the notification/deactivation process.

And that, in a nutshell, is the entirety of the bootstrap process. Just about every plugin I write nowadays incorporates some version of this structure:

  1. Check for the presence of a local autoloader
  2. Try to instantiate the main plugin class on the plugins_loaded action and run it.
  3. Display a notice and deactivate the plugin if anything went wrong.

Class File Organization

Next, let’s take a look at the file structure for this particular plugin.

Class file structure of the Board Game Collector plugin

By adhering to the PSR-4 standard for class autoloading, I’m able to organize the various classes that power my plugin into groupings relevant to their responsibilities. All class files at the root of the src/ directory have a namespace of JMichaelWard/BoardGameCollector, and from there, the namespace matches the relative path to the file. So, for instance, my CliService class, located at src/UI/Cli/, has a namespace of JMichaelWard/BoardGameCollector/UI/Cli.

The benefits of this approach are two-fold. First, when I need to make a change to a particular part of the plugin – say, updates to the API connections – I know exactly where I need to go, because everything is organized into top-level directories that describe what they are responsible for. Second, any classes referenced outside of that grouping can be easily located, because their namespace matches the file structure.

Today, many WordPress plugins still rely on a flat class structure which, sure, makes it easy to locate all of the class files, but I find that understanding the relationships between classes is far more challenging. This particular approach works for me, and perhaps it will work for you, too.

The Main Plugin File

Finally, let’s check out the main plugin file and see how things are structured.

There’s kind of a lot going on here, but in many ways, the main class file is a lot like the bootstrap file. Its job is to define a set of “services” – basically, processes for which the plugin is responsible for starting up – and make sure that those services are run. At this point in time, the Board Game Collector plugin has 5 primary services:

  • A ContentRegistrar, which is responsible for registering custom post types and taxonomies with WordPress.
  • An ApiService, which is responsible for registering custom API endpoints within WordPress and for communicating with the BoardGameGeek API.
  • A CliService, which is responsible for registering custom WP-CLI commands.
  • A CronService, which is responsible for setting up tasks that need to trigger at given intervals.
  • The Settings service, which is responsible for registering admin interfaces for working with the plugin inside of the WordPress dashboard.

Beyond that functionality, there are a few additional things I’d like to point out in this class file.

First, I’m using a Dependency Injection container called Auryn in this project. Auryn is, simply put, completely magical. On line 79 of the gist, the call to $this->injector->make passes in the current service class name to Auryn and leaves the instantiation of that object to it. If the class defines any other classes within its constructor, Auryn will load an existing instance of it if it finds one, otherwise, it will instantiate that dependency for you. The benefit is that your class constructors can be properly defined with the actual objects your class needs, making it easier to understand later what an object is made of. Auryn probably deserves a whole separate blog post of its own, so I’ll leave it at that for now.

Second, within the register_services method, I’m calling array_column on the resulting set of services and reassigning it to the $services property. This turns the indexed array into an associative array instead, and allows me – should I need it – to request a particular service object by its class name.

Lastly, after each of the service objects are instantiated, I pass the actual services to a register_service method, which passes in the main plugin file path to the objects that require it, and finally, calls their run methods to trigger the processes for those services. The benefit here is that register_service is type-hinted to the Service abstract class in OOPS-WP, meaning that if I add a service class name to the array inside of th main class, but forget to actually extend the abstract class, PHP will throw a fatal error. Errors are extremely helpful when attempting to abide by a given standard, and putting these guardrails in place for myself overtime have made me a better developer and made my own code a little more foolproof.

Summary

Hopefully this post gives you some ideas about approaches you can take to structure your own projects. I absolutely love working with object oriented code, and I’m hoping that as time goes on, we start to see more WordPress developers incorporating object-oriented practices into their plugins and themes. Clearly separating the responsibility of your code into sections, as I’ve demonstrated above, can make it easier for other engineers (or even your future self!) to understand what’s going on within your application, thereby reducing the time it takes to make fixes or to create brand new features.

If you happened to read this post and found it helpful or informative, please give me a shout on Twitter and let me know!