Meet wpshell – the power of WordPress at your prompt

Developing in WordPress is a lot of fun for me and there are great plugins that make developing and debugging WordPress code really simple. Debug-Bar, Debug-Bar-Extender and Debug-Console are my favorite WordPress plugins to do this.

But if you really live in WordPress code all day long you might sometimes wish that you can just log into it and do your thing without the need of leaving test scripts all over the place.

You can do this with wpshell, a tool written by my fellow Automattician Apokalyptik. Although this is a fairly unknown and well hidden piece of code it’s worthy to install it on your local development environment in order to dive right into WordPress. After adjusting some basic configurations wpshell gives you a command shell that accepts native PHP code as well as all the functionality your regular WordPress install would give you. And there is even more, it also parses all the tokens and lets you grab information about function definitions, their parameters and the like.

If this got you excited go ahead and watch this video showing wpshell in action and how it is installed.

Before we get started, there are some requirements and warnings:

• This is intended for advanced developers. If you don’t know what you’re doing you can easily mess up your WordPress install
• Although possible, I would not run this on production, but only in a local development environment
• You need to have a working installation of WordPress that will be utilized by wpshell

Here’s a quick walkthrough of the installation procedure:

• svn co http://code.svn.wordpress.org/wpshell wpshell

  (check out the wpshell repository)

• cd wpshell

  (get in the folder)

• vi wpshell

  (adjust shell variable and 2 occurences of the PHP path to your needs )

• vi wpshell-config.php

  (adjust HTTP_HOST, REQUEST_URI and other $_SERVER variables that might need adjustments to fit your WordPress install. You can easily check those values in your current WordPress installation. Adjust require statement to point to the wp-config.php of your WordPress install.)

If you did everything right you should now be able to use the shell. Here are some basics.

Invoking the shell:

• wpshell

  will get you a command prompt. Here you can enter native PHP code or WordPress functions or functions defined elsewhere in your project

• echo 'echo $blog_id' | wpshell

  will take the command(s) you pipe to the shell and execute them

• wpshell < /path/to/a/php/script

  will use the php script as source for the commands

wpshell also comes with a bunch of built-in commands to make your life easier. Here are some of them

Database queries:

• get_results $query

  returns the result of $wpdb->get_results

• get_var $query

  returns the result of $wpdb->get_var

• get_col $query

  returns the result of $wpdb->get_col

• get_row $query

  returns the result of $wpdb->get_row

Filesystem:

• ls [path]

  list the content of the current directory

• cd [path]

  change current working directory

• quit

  quit the shell

Reference:

• d $function_name

  displays the function definition

• f $function_name

  displays the function source

• fsearch $search_string

  search for a function matching the search string in the current working directory

• c $class_name

  returns the class source

• csearch $search_string

  search for a class matching the search string in the current working directory

That’s all nice, but what can I do with it? – The sky is the limit.

I personally use it like this; I wrote a small Coda Plugin that takes selected content and executes it in wpshell and throws the result back to a new tab in my editor. In this way I can just mark code fragments or queries and run them against wpshell right away.
I also created a small PHP script together with an AppleScript that allows me to search for a function and open the file it’s defined in directly in Coda and jump to the correct line or alternatively perform a php.net manual lookup and display the result in Coda.
If there is any interest I can make these scripts public as well. They are still very edgy though.
I also have a wpshell running inside a screen session and keep it always accessable via TotalTerminal.

Plans:

I did not have much time to look into it, but the code is so awesome that I hope to integrate it better in my IDE. I’m planning to setup the parameters in wpshell-config.php automatically when I fire up a wpshell from within Coda. It would traverse upwards from the opened file until it finds a wp-config.php and setup HTTP_HOST and path accordingly. It could also work by simply entering a URL and Coda would fire up a preview window in Chrome along with the wpshell adjusted to exactly this url.