Application Development
Developers Corner

Maintaining contrib modules using drush qd and PHPStorm

Mar. 18 2016
Shawn Smiley
Director of Engineering Operations

The folks over at Chromatic recently published an informative blog post on using Drush’s core-quick-drupal command.  Their post inspired me to find a way for Achieve developers to incorporate this new tool as they use PHPStorm to efficiently maintain contrib modules .  

Here at Achieve Internet, we rely heavily on vagrant machines for all of our project development needs.  However, there are times when we're simply patching or updating a contrib module and spinning up a vagrant is overkill. That’s where drush core-quick-drupal (aka drush qd) can play an exciting role in streamlining that process.

In this article, I’ll walk you through the process of using drush qd and PHPStorm to setup and maintain contrib modules on drupal.org.  I’ll use one of my own contrib modules - Webform Options Markup - as an example. But know that this process will work for any contrib or stand-alone Drupal module, theme, or profile.

 

Prerequisites

  • Local installation of PHP (5.4 or later)
  • Local installation Drush 7.x or 8.x that is globally accessible
  • PHPStorm (I’m using version 10.x, older versions may work)
  • PHPStorm Command Line Launcher has been created

 

Installing the PHPStorm Command Line Launcher

  1. Open a terminal window and type “which pstorm”.  If that comes back with “/usr/local/bin/pstorm” then you’re all set and don’t need to go further.  If not, continue with the steps below.
  2. Open PHPStorm and open any project
  3. Go to the “Tools” menu and select “Create Command-line Launcher…”
    Create Command-line Launcher menu
  4. Accept the defaults for creating a launcher and click OK.
    Create Command Line Launcher Dialog

You should now be able to launch PHPStorm from any terminal window by using the command “pstorm”.

Using drush qd to setup the dev site

The next handful of steps will use drush qd to download: a copy of Drupal, the contrib module you'll be maintaining, and any dependencies you'll need.  You can store these files anywhere on your local computer.  I store them under ~/Sites/contrib_modules.

Step 1: Create the base Drupal installation

Open a terminal window and enter the following commands:

cd ~/Sites/contrib_modules
drush qd --core=drupal-7.x --account-pass=admin --no-browser --no-server --yes webform_options_markup ctools,views,webform

 

In the above commands we’re doing the following:

  • Changing to the directory where we want our code to live (~/Sites/contrib_modules)
  • Telling drush qd to download and install Drupal 7 in the directory “webform_options_markup” and to download/enable additional contrib module “ctools”, “views”, and “webform”
    • We’re also passing along options to set the default, user 1 password and to make sure the PHP Web Server doesn't auto-start (but we’ll do that later through PHPStorm).

 

So the basic syntax for drush qd is:

drush qd --core=[drupal core version] [folder name for site] [comma separated list of additional modules/themes to install]

 

Step 2: Clone the contrib module we want to maintain

 
cd webform_options_markup/drupal-7.x/sites/all/modules
git clone --branch 7.x-2.x https://git.drupal.org/project/webform_optionsmarkup.git

 

Nothing fancy happening here! We've simply changed the sites/all/modules folder of the Drupal site we just created.  Then copy/pasted the git clone command from the "Version Control" tab of the module we want to work on.

 

At this point, we have everything in place code-wise to work on our module.  Now let’s setup PHPStorm.

 

Setting up PHPStorm

 

Configuring the PHPStorm Project

Launch PHPStorm and open the Drupal module we checked out above (~/Sites/contrib_modules/webform_options_markup/drupal-7.x/sites/all/modules/webform_options_markup).  Note that we’re opening a subfolder from where we created the project.  Drush qd puts all of the Drupal files under a subfolder with the same name as the Drupal core version you selected.

After you open the site in PHPStorm it'll immeditiately prompt you with a message asking if you’re working on a Drupal module.  Click the “Enable” link in the dialog:
Drupal support dialog

This will bring up a dialog asking for information on the location of the full Drupal installation.  Select the path to the root of this Drupal site.
Drupal Settings Dialog

 

Configuring Run Configurations

Now that PHPStorm knows about your Drupal module, tell it how to start up the built-in PHP Web Server.  We’ll setup two different run configurations.  The first configuration is a default and starts the PHP Web Server. The second also starts the PHP Web Service but also wipes the Drupal DB so we can reinstall the site.

In the top center of the toolbar, there's a drop down arrow with nothing next to it.  Click that arrow and then click on the menu option “Edit Configurations…”.
Edit configurations menu

 

Configuring the default run configuration

When the "Run/Debug Configurations" dialog appears, click the + icon in the toolbar and then click on the “PHP Built-in Web Server” menu option.
Add configuration dialog

 

Enter the following information into the run configuration dialog:

  • Name: Dev Site
    • This can be any name you want, it’s what will display in the toolbar.
  • Host: 127.0.0.1
    • I find using 127.0.0.1 works slightly better than using “localhost”.
  • Port: 8888
    • Can be any TCP port number that isn’t on use on your computer.
  • Document root: [Path to the root of the Drupal site.]
  • Click Apply

Dev site run configuration

Configuring the site reset configuration

When the "Run/Debug Configurations" dialog appears, click the + icon in the toolbar and then click on “PHP Built-in Web Server”.

NOTE: You can also Copy the configuration that we just created and simply edit that.

Add configuration menu

 

Enter the following information into the run configuration dialog:

  • Name: Dev Site (Clean)
    • This can be any name you want, it’s what will display in the toolbar.
  • Host: 127.0.0.1
    • I find using 127.0.0.1 works slightly better than using “localhost”.
  • Port: 8888
    • Can be any TCP port number that isn’t on use on your computer.
  • Document root: [Path to the root of the Drupal site.]
  • In the “Before launch” section we’re going to add a scripting command to reset the site.
    • Click the + icon and then select “Run External tool”
      Add external tool menu
    • Then click the "+" icon again in the External Tools list dialog
      Add external tool dialog
    • This brings up the “Edit Tool” dialog.  Fill out the form as shown:
      Configure external tool dialog
    • Click OK to close all of the open dialogs (approximately 3 times)

At this point, PHPStorm is now configured to start up the PHP Web Server any time you are ready to work on a module.  You should see the following 2 run configurations listed on the toolbar:

Completed run configuration options

Starting/Stopping the PHP Web Server

Now that your module or theme is configured in PHPStorm, you can start/stop the PHP Web Server at any time by selecting a run configuration and hitting the play button.

The play button in the top toolbar will start the web server with the selected configuration.

On the "Run" tab at the bottom of the window, you have options for restarting and stopping the web server.

You can now access your dev site by going to http://127.0.0.1:8888 in a browser.

Start/Stop options for run configurations

 

Wrapping Up

In this article, we’ve seen how to use “drush qd” to quickly setup a Drupal site that maintains a contrib module, theme, or profile.  We’ve also seen how to configure PHPStorm so you can start and stop the PHP Web Server whenever you're working on a contrib project.

 

Bonus

Being a developer, I love to automate things as much as possible. So I couldn't help taking the opportunity to wrap up most of these steps into a single shell script that you can call.  You can find a Gist of this script at https://gist.github.com/shawnachieve/49e7492c328f5e52db24.  Just add this function to the end of the "~/.profile" file on your computer and you're good to go.

 

 

The above script will perform the following:

  • Run the drush qd command in the ~/Sites/contrib_modules folder
  • Checkout your contrib module or theme from drupal.org
  • Attempt to pre-configure the run configurations in PHPStorm.
  • Launch PHPStorm and open the module folder for development.

 

Example usage (sets up a site for working on the views module):

 

NOTE: This script is still a work in progress and has a couple of issues that I hope to resolve in the coming weeks.  Specifically, the apparent issues are:

  • You have to close and reopen PHPStorm after the script initially launches it.  Otherwise, it doesn’t fully load the pre-configured settings that the script has defined.
  • You have to edit the run configuration to set your PHP Interpreter before you can start the web server.

 

RSS Feed Tags: 

More about Application Development, Developers Corner

API Documentation, API, Developer Portal
Below is a comparison of the features SmartDocs and Swagger UI offers out-of-the-box for the Drupal-based developer portal. The information here is to highlight the difference between two commonly used modules and to make it clear what could work best for your business.