PHPUnit tests and WP-CLI

I recently discovered an easy way to add unit tests to my plugins. I’ve been using WP-CLI for years now to set up new local installs of WordPress and found out it has a command specifically for setting up PHPUnit for plugins. This post is partially for my future self so I can remember how to do all this. FYI, I’m on a Mac, so all the commands will be OS X-specific.

Install and Configure PHPUnit

Start by installing PHPUnit using Homebrew:

brew install phpunit

That installs the latest version of PHPUnit and makes it ready to use with the global keyword “phpunit”.

Next, use WP-CLI to setup the test suites and such needed for PHPUnit. I recommend running this command from the plugin’s directory.

wp scaffold plugin-tests my-plugin

Replace the “my-plugin” part with your plugin name.

If you aren’t already in your plugin directory, change to that now. Then you’ll run the installation bash script.

bin/install-wp-tests.sh wordpress_test root '' localhost latest

Notes about this command:

  • ‘wordpress_test’ is the MySQL database created by this script and used for testing
  • ‘root’ is your local MySQL user
  • ” is where your local MySQL user password goes
  • ‘localhost’ is where you MySQL server is located
  • ‘latest’ changes the version of WordPress to use for testing.

Once you’ve run this script, you’re ready to start writing tests and running them using the ‘phpunit’ command. Here’s the rub though: the script installs WordPress and the testing suite in the /tmp directory. Why is that a  problem? On my computer, at least, the /tmp directory removes anything installed there upon reboot. Which means I need to re-run the tests bash script every time I reboot the computer.

Since we developers prefer not repeating ourselves, here’s how to configure things for a more permanent solution.

Solution

What I’m advising here is to move the stuff installed in /tmp to somewhere else, then fix all the references so they still work. So, run all of the above, then navigate to your /tmp folder. Move the /wordpress and /wordpress-tests-lib folders to another location outside the /tmp folder. I moved mine into a directory called unittests in my Dropbox folder.

Go to your Home folder and either open or create the .bash_profile file. You’ll probably need to tell Finder to show Hidden files first. In your .bash_profile file, add the following line, using your new directory location:

export WP_TESTS_DIR="/Your/New/Folder/Location/unittests/wordpress-tests-lib"

This line tells the PHPUnit bootstrap.php file where to find the test WordPress install and test suite files.

Now, go to the wordpress-tests-lib directory and open the wp-tests-config.php file. Edit the ABSPATH constant to the ‘/wordpress’ directory you copied over from /tmp earlier. Something like:

define( 'ABSPATH', '/Your/New/Folder/Location/unittests/wordpress//' );

Save the file and reboot your computer. Now, the tests setup by WP-CLI know where the testing WordPress is located, it doesn’t disappear when you install updates or reboot, and you can create and run PHPUnit tests for your plugins!

A Guide to Using the WordPress Plugin Boilerplate

For several years now, I’ve been building plugins using the WordPress Plugin Boilerplate project. In 2015, I gave a WordCamp talk about how to use it. Over the past few years, I’ve answered questions about how to build plugins with the boilerplate. Since there is no official documentation, I hope these posts serve as some unofficial documentation. I covered most of this introductory material in my WordCamp talk. However, I’m planning more detailed posts, additional code examples, and topics I didn’t cover in the presentation. I’ll also offer some shortcuts and potential improvements, in case you want to fork the boilerplate.

When I first began writing plugins, I did what most beginning developers do – copy and paste code samples from the Codex and/or another developer’s blog. Each plugin eventually worked, but I still cringe when I look at that code. Many of those first plugins were giant, one-file plugins. Over time, I learned better methods for writing code and eventually discovered the WordPress Plugin Boilerplate. Since then, I’ve used either the boilerplate or my own fork for even the simplest plugins.

What Is The WordPress Plugin Boilerplate?

A good starting place is understanding what the boilerplate is and the history behind it. The boilerplate is a standardized, organized, object-oriented foundation for building high-quality WordPress plugins. There are some simple examples of how the parts work together as examples for building your plugin. In addition, the boilerplate includes easily overlooked plugin features like inline documentation and translation files.

Tom McFarlin, a well-respected developer from Atlanta, GA, developed the boilerplate. He wanted to prevent needlessly writing the same code each time he began a new plugin. The boilerplate is currently on version 3, which included a major restructuring. In March of 2015, the boilerplate project passed to Devin Vinson of Tampa Bay, FL.

How Do We Use The Boilerplate?

Since there is so much information to cover, we’ll cover each subject in a separate post. This introductory post will serve as a table of contents for the series. Throughout this series, we’ll build an example plugin titled “WP Starter Plugin”. It will include typical plugin parts like settings pages, widgets, metaboxes, etc. This gives you a major head start when creating plugins in the future.

Posts In This Series

  • Why Use the Boilerplate?
  • The Structure of the WordPress Plugin Boilerplate
  • Understanding the Loader Class
  • Using the Plugin Generator
  • Editing the README

Parker and WordPress Theme Development

Lately, I’ve been playing with a CSS analysis tool called Parker created by Katie Fenn. Parker examines your stylesheet and gives a treasure trove of metrics. While some of these metrics are merely interesting factoids (like the number of CSS rules), others offer constructive criticism for improvement. The general philosophy is to create more maintainable CSS by simplifying your stylesheet.

Harry Roberts, of csswizardry.com, has an excellent write-up about using Parker. He explains some of the options and offers some ideal scores to shoot for, which I’ll list and explain in later posts. WordPress developers will need additional code to change the WordPress-generated code, like in menus.

In the following posts, I’m going to use Parker to test my fork of the _s starter theme and made optimize it based on the results. I’ve based every project over the past two years on _s and advise anyone learning theme development to start there. This post will serve as a sort of table of contents; I’ll link to each post as they are published.

Why Use Parker?

As I mentioned above, Parker is good for reducing the size and complexity of your stylesheet. While that’s not a big concern for small projects, for larger projects, this can be a lifesaver. Maybe other developers come along and start adding new features, new CSS methods (floats vs flexbox vs grid) or using different methods (BEM vs Atomic vs random…) and your stylesheet gets more and more complex.

Ideally, the newer developer(s) would check the stylesheet for existing styles that accomplish what they want. Since this doesn’t happen many times, Parker can at least tell them whether their code and existing code can be simpler.

Posts in This Series

How to Add the jQuery UI Datepicker to a Plugin

Updated – 4/14/2015

I’ve since learned a better way to do this. It essentially does the same thing, the same way, but using better WordPress practices. Use the code in this gist instead of what’s below:

/**
* Adds the datepicker settings to the admin footer.
* Only loads on the plugin-name settings page
*/
function admin_footer() {
$screen = get_current_screen();
if ( $screen->id == 'settings_page_plugin-name' ) {
?><script type="text/javascript">
jQuery(document).ready(function(){
jQuery('.datepicker').datepicker({
dateFormat : 'D, m/d/yy'
});
});
</script><?php
}
} // admin_footer()
add_action( 'admin_print_scripts', array( $this, 'admin_footer' ), 1000 );
/**
* Enqueues the built-in Datepicker script
* Only loads on the plugin-name settings page
*/
function enqueue_scripts( $hook_suffix ) {
$screen = get_current_screen();
if ( $screen->id == $hook_suffix ) {
wp_enqueue_script( 'jquery-ui-datepicker' );
}
} // enqueue_scripts()
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
/**
* Enqueues a Datepicker theme
* Only loads on the plugin-name settings page
*/
function enqueue_styles( $hook_suffix ) {
$screen = get_current_screen();
if ( $screen->id == $hook_suffix ) {
wp_enqueue_style( 'jquery.ui.theme', plugin_dir_url( __FILE__ ) . '/css/datepicker.css', array( 'jquery-ui-core', 'jquery-ui-datepicker' ), $this->version, 'all' );
}
} // enqueue_styles()
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_styles' ) );

 

datepicker-head

I recently decided to dive into jQuery and figure out how to add a Datepicker to the Seminar system plugin I’m building for the Curb College at Belmont.  Thankfully, I didn’t need to write one from scratch because jQuery UI already makes a great Datepicker and including it in a plugin is super easy.  While I owe a great deal to Zigpress’s great tutorial, the instructions are unfortunately outdated, so I’m going to update them here.

If you’re using WordPress 3.3 or higher, then the jQuery UI Datepicker is already included, otherwise you should update your WordPress install or include the files.  In either case, you will need to include a theme for the Datepicker and add a few lines of code.  FYI, all the following code samples are written within a class, which you should be doing in your plugin, but feel free to adapt as necessary.  First thing, in your __construct() function, you’ll need to add a few lines that tells the plugin to reference a function that will include the jQuery references.

Add Actions

// Add jQuery calender
add_action( 'admin_print_scripts-post.php', array( $this, 'seminar_scripts' ), 1000 );
add_action( 'admin_print_scripts-post-new.php', array( $this, 'seminar_scripts' ), 1000 );
add_action( 'admin_footer', array( $this, 'admin_footer' ) ); 

In my plugin, I’m using the Datepicker for a meta box on the custom post type pages in the admin area, so I’m using the actions admin_print_scripts-post.php and admin_print_scripts-post-new.php and they both call the ‘seminar_scripts’ function.  I also have the admin_footer action call the admin_footer function.  Calling the Datepicker only on the required admin pages lowers the overhead for loading the Admin pages, keeping things as small as possible without sacrificing functionality.

Enqueue the Script and Theme

Now we have to functions to define two functions: seminar_scripts() and admin_footer().

function seminar_scripts() {
   global $post_type;
   if( 'cemb_seminar' != $post_type ) { return; }
   wp_enqueue_script( 'jquery-ui-datepicker' );
   wp_enqueue_style( 'jquery.ui.theme', plugins_url( '/css/jquery-ui-1.8.17.custom.css', __FILE__ ) );
} // End of seminar_scripts() 

Seminar_scripts() starts by checking what post type you’re looking at.  If it’s not cemb_seminar (my custom post type – be sure to change this to match your plugin), then stop.  If it is cemb_seminar, then enqueue the Datepicker and it’s theme.  If you use a different folder structure for your plugin, you’ll need to change the plugins_url() line to match your structure.

jqui-theme

For now (2/23/2012), you will need to include a theme for your Datepicker.  WordPress doesn’t include a theme for the Datepicker, but that should be resolved in a coming update.  To get a theme, go to the jQuery UI ThemeRoller, select the Gallery tab on the right sidebar, and choose your theme.  I’m using Smoothness because I think it most closely matches the WordPress Admin UI.

jqui-download

Clicking the Download button under a theme will take you to a page where you can select options for your jQuery UI download.  Select your theme from the Theme drop menu, select the stable version, and click the Download button.

zip-folder

When it finishes downloading, unzip the file and go to the css > smoothness folder.  In my plugin, I’ve got a CSS folder.  Drag the jqery-ui-1.8.17.custom.css file and images folder from the zip file into your plugin’s css folder (or wherever you pointed the plugins_url() line in the enqueue statement in seminar_scripts()).

Add the jQuery Script

function admin_footer() { ?>
   <script type="text/javascript">
      jQuery(document).ready(function(){
         jQuery('.seminar_date').datepicker({
            dateFormat : 'D, m/d/yy'
         });
      });
   </script><?php
} // End of admin_footer() 

Admin_footer() includes the actual jQuery statement to make things happen on the page in the footer of your admin page.  There are two things here you will need to customize for your plugin: the selector and the date format.  jQuery works by looking at the page and finding a part of the page – aka the selector – and performing the script.  My selector is the CSS class (.seminar_date) for the date field in the meta box.  You’ll need to modify that to match the CSS class (or ID) for your date field.  The date format is just how the date is printed on the page.  For my plugin, I choose a format like: Mon 2/22/2012.  You can see all the options on this page.

That’s it!  Once you’ve added all that code and uploaded the jQuery UI theme, test it out and see the Datepicker appear when you click in the field you selected in the selector.

How to Change the New Mail Sound in Office 2011 for Mac

Microsoft Office for Mac 2011 doesn’t have an easy way to replace the sound alerts, but with a little digging, it can be accomplished. “Message for you, sir!”

Outlook 2011 IconI just got Office for Mac 2011 yesterday and I’ve been putting it through its paces.  So far, I’m impressed.  Sure, the “Ribbon” takes some getting used to, but overall, I haven’t had any insurmountable issues.  Two things that I’d like to see improved: 1) there’s no way to create an automatic archive for back ups like on the PC Outlook.  2) There’s no easy way to change the sound alerts.

This second one began to bother me today.  I’m a fan of Monty Python and several years ago started changing my new mail alert to a recording from the Holy Grail when Lancelot’s trusty servant Concorde gets shot with an arrow and says “Message for you, sir!”  I wanted to change that setting in Office for Mac 2011, but the alert options only has a checkbox – the alert is either on or off.  After some Googling and digging, here’s how to customize your alerts sounds for Office for Mac 2011:

Close Outlook

Open your hard drive and go to Applications > Microsoft Office 2011 > Office

show-package-contents

Right-click (or control+click) on OutlookCore.framework and select Show Package Contents

resources-wavs

Inside the Resources folder are the wav files for the alerts sounds.  To change the “new mail” sound, we want to replace the newmail.wav file by renaming the new alert to the same name and copying it into this folder.  Select to replace the file when asked.

Open Outlook.

Now, when you get a new message, it will play your new message wav instead of the default one.  It would be nice if there was a way to do this without digging through framework files, but until then, this will work for you!