A simple plugin base for WordPress plugins that provides some boilerplate functionality.
A simple plugin base for WordPress plugins that provides some boilerplate functionality.
Read the comments in the code for explanations and steps for turning the boilerplate into your own plugin.
wp-plugin-base
directory and wp-plugin-base.php
file with the name of your plugin replacing wp-plugin-base
.Plugin_Name.class.php
and Plugin_Name_Options.class.php
files in the assets/classes/
directory with the name of your plugin replacing Plugin_Name
.wp-plugin-base.php
.Plugin_Name
or any derivation of that, you should change it to the actual name of your plug-in and follow the capitalization scheme that was used. I generally do a Find/Replace on all files in this plugin's directory. (Examples: PLUGIN_NAME, plugin_name, Plugin_Name, PLUGIN NAME)wp-plugin-base.php
file. This makes it easier to refer to paths and URLs that are relative to your plug-in. It already defines PLUGIN_NAME_DIR
and PLUGIN_NAME_URL
for easily including other files you add to the plugin's directory.assets/classes/Plugin_Name_Options.class.php
and add any tables, options, or capabilities that you need. This class has some methods for handling prefixing names and logging errors to the debug.log
file, as well.assets/classes/Plugin_Name.class.php
and begin adding any functionality you need. This class has some default methods for setitng up tables, options, and capabilities that you may find useful. It also includes a method to facilitate performing any database maintenance necessary when updating your plugin's version.assets/classes/
directory, and for better integration with our basic methods and options, make them extend the class previously called Plugin_Name_Options
.assets/css/
directory. The directory structure in place favors using SCSS files and SASS as a preprocessor, but you can set this directory up however you prefer. I keep any admin area styles in a separate css file with -admin
appended to the name so that I can enqueue them separately.assets/js/
directory. There are two very basic js files with empty modules already in this directory, you can work from them or begin creating your own files as needed. Just like with the CSS files, I keep admin area JavaScript in a separate file iwth -admin
appended to the name.wp-base-plugin.php
), or you can create your own initialization method that configures your actions.$v_num
attribute of the Options class (previously called Plugin_Name_Options
) to reflect the new version. This value is stored as an option in the WordPress database so that you can easily perform any maintenance necessary when a user upgrades the plugin.deploy.sh
file to reflect the SVN information for your WordPress plug-in and user account, then navigate to the folder for your plugin in Terminal, then enter ./deploy.sh
, and let the script work its magic. You will find some deployment notes at the end of this README.Plugin Prefix
Define a prefix in the Plugin_Name_Options class for your option names, tables names, capabilities, page slugs, etc. so you only have to write it once:
//prefix for option names, table names, and capability names
public $prefix = 'plugin_name_';
You can use the $this->fix_name($slug)
method of the Plugin_Name class to append this prefix to any string.
If you want to refer to the prefix in the Plugin_Name class, you can reference it as $this->options->prefix
.
Plugin Debug Namespace
Define a namespace in the Plugin_Name_Options class to be prepended to any messages you have your plugin send to the debug.log so you can easily find your debug statements in the log.
//namespace for any Debug messages
public $namespace = 'PLUGIN NAME';
If you use the $this->log($msg, $namespace)
method in the Plugin_Name class, you can send it a custom namespace or the namespace defined in the Plugin_Name_Options class will be used.
If you want to refer to the namespace in the Plugin_Name class, you can reference it as $this->options->namespace
.
Capabilities
Define capabilities in the Plugin_Name_Options class by adding them to the associative array in the set_capabilities()
method.
The array key for a set of capabilities should be the required capability a role needs for your capability to be added.
In the example below we are adding a capability that requires the manage_options
capability. NOTE: We are using $this->prefix
to prepend our plugin prefix to the capability name
//set up capability array
private function set_capabilities() {
//add capabilities to this array as 'required_capability' => array('capability_to_grant')
$this->caps = array(
'manage_options' => array(
$this->prefix . 'capability'
)
);
}
I generally refer to these capabilities when adding admin pages or checking user access by refering to their array key: $this->options->caps['manage_options'][0]
.
If you have a lot of various capabilities, you may want to set up an array mapping of capability slugs and reference them that way.
In the future I may shift to using a slug for each capabilities key and mapping them to a simpler point of reference.
Options
Define options in the Plugin_Name_Options class by adding them to the associative array $this->options
.
The options array will be JSON encoded and decoded when being stored and retrieved from the DB.
//set up options array
private function set_options() {
$this->options = array(
$this->prefix . 'version' => $this->v_num,
$this->prefix . 'options' => array(
//add options to this array as 'option_name' => 'option_value'
//this allows us to only store two options in the table
//one will keep our version number and the other will keep a JSON encoded
//string of all of our other options
)
);
}
To access any of the options in the Plugin_Name class, you can reference them like this: $this->options['slug']
.
To access the current options values in the Plugin_Name class, you can reference the settings array: $this->settings['slug']
.
Tables
Define tables in the Plugin_Name_Options class by adding them to the associative array $this->tables
.
//set up table array
private function set_tables() {
//set the table name slug as a key for the $this->tables array
//and add the MySQL CREATE statement as the value for that key
$this->tables['main'] = "CREATE TABLE `" . $this->prefix . 'main' . "` (
`ID` int(15) NOT NULL AUTO_INCREMENT,
`column_name` varchar(255),
PRIMARY KEY (`ID`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1"
;
}
To access the table names in the Plugin_Name class, you can reference them like this: $this->tables['slug']
.
Updating
If you need to perform maintenance when updating your plugin, tie into the pre_update_option()
method in the Plugin_Name class.
There is a comment that starts //IMPORTANT
to show you where to inject your update code.
WordPress Plug-in Repository
Make sure to fill out the readme.txt
before submitting to the WordPress repository and include some screenshots if you can.
Here is a link to WordPress' example readme.txt
: http://wordpress.org/plugins/about/readme.txt
Deploying
So, you want to host your plug-in on GitHub but also have it available in the WordPress Plug-in Repository? No problem.
I've included a version of @BFTrick's' deploy.sh
script found here: https://gist.github.com/BFTrick/3767319
All you need to do is edit the script to reflect the SVN information for your WordPress plug-in and then navigate to the folder for your plugin and type ./deploy.sh
and let the script work its magic.
A few notes about deploying:
readme.txt
so make sure they are the same.0.0.1
, 0.0.2
, etc.deploy.sh
to your .gitignore
(I recommend globally) so you don't give anyone access to deploy your plugin.