How to Set Up Underpin For a Single Site

Underpin is a powerful WordPress plugin framework that is designed to make working with WordPress feel more-modern, and to help keep your technical debt low. It does this by sticking to a consistent pattern for registering just about everything on your site. I talk about the benefits of Underpin in this introductory post, but in the meantime, let's talk about how to actually set up Underpin quickly using Underpin's plugin boilerplate.

There are many ways to approach installing Underpin, and each one has their own benefits. This post covers how to set up Underpin for a single site. This approach works best if these two things are true:

1. You have multiple plugins or themes on your site that will use Underpin
2. You do not intend to distribute any of these plugins, or themes outside of this single site

This approach will install Underpin as a must-use plugin. This means that Underpin is loaded extremely early in the WordPress runtime, and ensures that it is always fully-loaded regardless of how early you use it.

Install Underpin as a MU (Must-Use) Plugin

The first thing you need to-do is actually install Underpin on your site. Underpin uses Composer to handle its dependencies,

Inside the wp-content directory, create a new directory called mu-plugins. If mu-plugins already exists, then skip this step.

Now create a composer.json file inside the mu-plugins directory. Most of this is the default settings for a composer.json file, the key difference is that extra.installer-paths is tweaked to force wordpress-muplugins to simply be installed directly in the vendor directory. This is necessary because Underpin is considered a mu-plugin by Composer, and will install in an improper directory, otherwise.

{
    "name": "wpda/muplugin",
    "type": "plugin",
    "require": {},
    "extra":{
    	"installer-paths": {
	      "vendor/{$vendor}/{$name}": ["type:wordpress-muplugin"]
	}
    }
}

Next, create a new PHP file inside the mu-plugins directory. It can named be whatever you want it to be. WordPress will automatically include this file, and run it on every page load. This happens really early in WordPress's runtime so there are some limitations to this, but for our needs it's perfect.

Use this code to include composer's autoloader. This will automatically install and set up Underpin so you can use it anywhere else. This includes any plugins custom to this site, or your theme. Essentially, this makes Underpin as close to core functionality as possible. The only caveat is you have to remember to upload the mu-plugins directory to your live site.

<?php
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

// Load Underpin, and its dependencies.
$autoload = plugin_dir_path( __FILE__ ) . 'vendor/autoload.php';

require_once( $autoload );

Now, let's install Underpin. Open up your command-line, navigate to your site's mu-plugins directory, and then run this command:

composer require underpin/underpin

Booya! You now have Underpin installed. Now, let's use it in a plugin.

Set Up The Boilerplate Plugin

We're going to use Underpin's plugin boilerplate to help set up this plugin quickly. This plugin does a few key things for us:

1. It sets up our Underpin plugin instance
2. It comes with a WordPress-ready Webpack config
3. It sets up the file headers that WordPress needs in-order to recognize the file as a plugin

To use this, navigate to wp-content/plugins and clone the boilerplate. The example below will both clone the boilerplate and delete the git history for the boilerplate. This allows you to create your own repository if you want, without including the history for the boilerplate. You probably don't want that, anyway.

git clone https://github.com/Underpin-WP/underpin-plugin-boilerplate.git plugin-name

Then you'll need to-do a few find/replaces in the boilerplate.

1. Replace plugin-name-replace-me with your plugin name. it can be whatever you want, just make sure spaces use dashes, and it's all lowercase.
2. Replace Plugin Name Replace Me with your plugin name, only this time whatever you want just has to use spaces and Title Case)
3. Replace plugin_name_replace_me with your plugin name, but this time use snake_case
4. Replace Plugin_Name_Replace_Me with your plugin name, but this time use Upper_Snake_Case
5. Replace Plugin Description Replace Me with a description of your plugin

At this point, your plugin's bootstrap.php file should look something like this:

<?php
/*
Plugin Name: Custom Plugin
Description: Plugin Description Replace Me
Version: 1.0.0
Author: An awesome developer
Text Domain: custom_plugin
Domain Path: /languages
Requires at least: 5.1
Requires PHP: 7.0
*/

use Underpin\Abstracts\Underpin;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Fetches the instance of the plugin.
 * This function makes it possible to access everything else in this plugin.
 * It will automatically initiate the plugin, if necessary.
 * It also handles autoloading for any class in the plugin.
 *
 * @since 1.0.0
 *
 * @return \Underpin\Factories\Underpin_Instance The bootstrap for this plugin.
 */
function custom_plugin() {
	return Underpin::make_class( &#91;
		'root_namespace'      => 'Custom_Plugin',
		'text_domain'         => 'custom_plugin',
		'minimum_php_version' => '7.0',
		'minimum_wp_version'  => '5.1',
		'version'             => '1.0.0',
	] )->get( __FILE__ );
}

// Lock and load.
custom_plugin();

And that's it! You now have a plugin all-set and ready to use Underpin.