Posted on

ApiGen versus phpDoc

So last night I went down the path of connecting phpDocumentor2 (phpDoc) to my code so I can find key elements in the classes and objects without having to search through the code editor. That works fine, but it is often faster for me to have an index of the classes, methods, and properties in a browser window. Even better, by publishing on the public CSA site I know can use Google to search my own docs. That is a nice bonus.

This morning, while researching custom templates, I came across a competing tool that threatened derailment of my phpDoc efforts. I came across comments that phpDoc was inferior, not updated, and had poor documentation. The project had been ignored for a few years. Turns out that much of that has been addressed since the phpDoc efforts have continued once again, though there are still plenty of gaps in the documentation of the phpDocumentor2 tool kit. After a brief run with ApiGen, I am back on the phpDoc trail.

Official Website

I was a bit apprehensive about ApiGen from the start. Why? The official website for ApiGen seems less polished than the phpDoc site. If they can’t make a great first impression on their website, what are the chances they can create decent HTML docs from my code comments? Turns out I liked the generated HTML better than their website. While phpDoc does have holes in their website presentation as far as features sets, command line options, etc. It is easier to find what I am looking for and seems to have much more documentation online than ApiGen. Maybe ApiGen has more documentation, but if it is not easy to find that doesn’t make me more efficient.

Winner: phpDoc


The installation of both products was about the same.   Use pear to setup a remote archive, and run pear to install the product.    However there was one or two fewer steps in installing phpDoc over ApiGen.   The big difference, however, was the facilitators required by ApiGen versus phpDoc.  phpDoc required far fewer libraries and add-on packs than ApiGen and produces better results.    phpDoc is either utilizing more of my CentOS 6 default PHP libraries or it just needs less in the “other frameworks” department to accomplish a similar goal.

Winner: phpDoc

NetBeans Integration

As for the NetBeans integration, they are both fairly similar.  Neither option functions very differently from the other.   They both need a target output directory set.  However, for some reason ApiGen requires you to locate the full path to the executable.  phpDoc just automatically worked.  Slight advantage: phpDoc.

Winner: phpDoc

Generated Site : Weight

This is one place where I think ApiGen wins out.  The overall “weight” of the produced site for the code documentation has less stuff to push around to and from the public server.  That also means that the stuff the pages have to load when people are viewing the site is less.   However I think there is a trade off on quality and possibly mobile-aware presentation.   Based on sheer “bits and bytes” to get the page online, ApiGen is lighter.

Winner: ApiGen

Generated Site : Quality

While I do like the search feature of ApiGen, I quickly discovered it is not a general “search any word” type of search we all are accustomed to on any site.  It is more of a “type a few characters and find a class name” search.  At least out of the box that is how it seems to be configured.   So while the search feature seemed like a plus, it really isn’t that useful to me.     Overall the look and feel plus ease of navigation of the phpDoc generate site works better for me.

Winner: phpDoc


Overall, I found phpDoc to be the best option at this point.   ApiGen isn’t bad, but today phpDoc edges out ApiGen in the areas that matter most to me.

You can compare the results of my simple Tagalong test here:

Tagalong Code Docs from ApiGen

Tagalong Code Docs from phpDoc

Posted on

Geeking Out With Netbeans and PHPDoc

I’ve been playing with phpDoc and NetBeans a lot lately.  I’ve found that having well documented code using the phpDocumentor 2 format makes for a much more efficient coding environment.   For one thing, if you have NetBeans setup properly and are using PHP classes that are fully documented, writing a line of code is as simple as typing a few characters.  NetBeans will find the objects you are looking for and list the properties and methods as you type.

That makes for some fast coding when typing something like $this->plugin->currentLocation->MakePersistent().  When everything is setup properly and the classes are properly documented I can type $t<tab>p<tab>c<down><tab>M<enter>.    While it may look like a lot of typing when spelled out essentially I am typing “$ttptcdtme”, or 10 characters instead of somewhere around 70.    Being 7x as efficient when writing thousands of lines of code is a HUGE bonus.

GitHub Markdown Docs for Code

Auto-complete shortcuts alone is one good reason to use a strong IDE like NetBeans along with a good code commenting/documentation solution like phpDocumentor2.   However tonight I found a cool new trick that I stumbled upon while trying to generate code documentation via GitHub.    I had learned a couple of weeks ago that I could use the command-line PHPDoc tool and a open source GitHub project called PHPDocMD to convert my code comments to XML and convert that to markdown (MD) that GitHub likes.   It creates OK results that are out on the public code repositories at Github.

So what is that new trick?  Well, there are 2 distinct parts.

Autogenerated HTML Docs for Code

Turns out there is a plugin for NetBeans that I’ve been ignoring.  For some reason I just happened to figure out that the “Generate Documentation” menu that appears when I right-click on a project in NetBeans actually has some use.

Yeah, I’m slow like that sometimes.

Turns out that under that menu is a submenu that has “ApiGen” and “PHPDoc” listed there.    Interesting.    That could be useful.

I went to the project, right-click, and select properties.  Sure enough, there is a setting for “PHPDoc” and it asks for a destination directory.  Basically asking “where do you want me to dump all the auto-generated documentation for your project?”.    Well it turns out that during my journey toward publishing code documentation on GitHub with MD, I had cloned the GitHub documentation repository to a local path on my development system.   I already had a folder full of code docs for my main plugin as well as several add-on packs.   So I pointed the output for my Netbeans “PHPDoc” setting to go there.

I go back, right click on the project, and select the Generate Documenation/PHPDoc.

Sure enough, NetBeans crunched my code comments and a few minutes later my Firefox browser window pops open and I see a pretty darn cool HTML site on my local box that has a full navigation menu for all of the classes I am using in my project, the properties, the To Do lists from my comments and more.  All this created because I’ve been taking a bit more time to fully comment the code.  Nice!

Settings Up For Auto-Publishing

Ok, so now on my dev box I have some pretty nice code docs that I can generate with a couple of mouse clicks.   That is helpful with a large project with multiple add-on packs.   But then I start thinking, why just keep it local?   The code is open source.  I have other developers that want to learn how to tweak the code for their own purposes.  I have third party developers looking for documentation and examples on how to do things so they can write efficient add-on packs.    Why keep the info all locked up on my dev box?

Well, I learned a neat trick a couple months ago with NetBeans.    I can have a local git repository on my development system but setup NetBeanswith a new “remote source” project.

So here I am with my commented code in my WordPress plugin directory that is fully commented and connected to a GitHub repository.   In another “docs only” directory outside of WordPress I have my PHPDoc generated HTML and MD files that I was previously only publishing to GitHub Wiki Pages, but now thanks to NetBeans I am also surfing locally on my dev desktop.     I realize I can auto-publish these code docs to my public website.

I create a new NetBeans project right next to my plugin code project.   I call it “store-locator-plus-codedocs” and set it up as a new PHP Remote Source project.   I tell it the local source on my box is the folder that I was storing the PHPDoc and MD files in for GitHub, which now contains my NetBeans-generated HTML files as well.    For a remote location I tell it to use my SFTP connection to the Charleston Software Associates website.  I jump on my website and make sure there is a new codedoc directory with a blank readme.txt file there.  If you don’t have SOMETHING for NetBeans to download from the remote source it thinks you screwed up and won’t continue…. minor flaw IMO, but easily remedied.    I then click OK.  It shows me the readme.txt with a checkbox to download it.    Click OK and BAM… there is a new project with the blank readme.txt plus all of the MD and HTML documents that were already on my local dev box.

OK, so kind of “so what” at this point, but here is where it starts getting cool… at least from a geek perspective.

Push The Initial Content

Now I need to “seed” the public website with the already-created content.   In NetBeans it is easy enough. Just highlight all the files in the project, right click and select upload.    Within a few minutes the entire HTML sub-site is uploaded to the server.   Just like any FTP program.   Nothing to it.

However now if I make any changes to those file with the editor two things happen, it saves a local copy on my dev box and it auto-publishes that updated to the live server in near-real time.    Since my local dev box has version control via GitHub, I can also quickly commit and push those edits also from inside NetBeans and make sure they are saved to the code repo.

But… I’m not going to ever edit those docs by hand.  They are auto-generated code documents that come from my well-formatted comments.  So the RIGHT way to edit them is to continue cleaning up and augmenting the code comments to make sure they are PHPDoc compliant.

So that is kind of cool.  My code docs are now auto-posting to my live server, saving on my dev server, and are one click from being saved and committed back to GitHub.  I can even add on more step and create a second copy in MD format for publication right next to the source code on GitHub.

But this is what really made me think “shit this is kind of cool”…

Auto-Publishing Code Comments

So I have all this stuff setup, my code project and my documentation project are both open at the same time in Netbeans.    I forget all about it as I start getting back into code writing.     I edit a method for one of the add-on packs and of course I go and update the comments about that method to reflect the latest changes.  I see another comment that is not complete and fill that out.

Save the code.  Commit the code so it publishes to GitHub.

A few more edits to code and comments later I decide… let’s generate the documentation before I sign off tonight…

I right click on my code project and select “generate documentation”.

Auto-magically the documentation project updates itself.   It saves a copy locally to my dev box with the new docs in place then auto-publishes to the public website with no intervention on my part.   As I setup the rest of my plugins with this system you will be able to find all the code docs on the bottom of the Technical Docs page on my site.   You can see my first auto-published work for Tagalong here, though I’m nowhere near done cleaning up the comments and naming conventions on my method to make this all “gussied up” for public consumption, but it’s a good start.

Maybe I’m just extra-geeky, but I thought that was cool… especially when the code docs actually look pretty darn good IMO, especially since they were created from nothing but /** This method does something.  @var string $this – does that **/ comments in the code.

I also know that with a few lines of script I can not only save locally and publish nice looking docs to my public site but also commit the code back to the GitHub repository while auto-generating the duplicate MD docs for the GitHub Wiki.

Yeah, I’m a Code Geek… and I’m not ashamed to admit it.

Posted on

Netbeans, phpDoc, and WordPress

A posting from our private “Tech List”, a list I share with select tech geeks mostly from the days at Cyber Sprocket Labs.   We tend to share high end tech tips that only geeks would find interesting.    I am posting here for easy reference for “The Tech List” groupies.

My Intro To Netbeans

9 months ago Chase was showing me NetBeans on his desktop.   It had some cool features for PHP like auto-complete and some very handy code lookup tools that reminded me of Visual Studio without all the weight.

 I wish I had learned about the NetBeans environment a long time ago.    NetBeans+ GitHub + SmartGit have made my coding at least twice a productive when it comes to PHP work, especially with complex WordPress plugin code.
In the past few months, while working in NetBeans, I’ve been refining my phpDoc skills.  This is EXTREMELY handy in making coding far more productive.    Here are some of the things I’ve learned that I wish we had all known about at Cyber Sprocket.    With the right tools it makes coding for people with senility (me) easier.

Effectively Using Netbeans for WP Dev

1) Wrap your ENTIRE plugin into a single instantiated object.
My plugin invocation now is basically something along these lines:
DEFINE(blah,blah) // a few of these help with WordPress stuff, like plugin version
class MP {
class MP_Error extends WP_Error {}
add_action('init', array('MP','init');
That is pretty much it other than the singleton.
2) Learn how to create and use singletons PROPERLY in WordPress
It must be a static method.
It should return itself as an instantiated object.
Set minimal properties as needed, not the entire WPCSL object here.
public static function init() {
    static $instance = false;
    if (!$instance) {
        $instance = new MP;
    return $instance;
3) phpDoc the class
In netbeans you go back to just above class MP {} and type /** after starting the frame of the class with properties and methods in place.
It will AUTO-CREATE the template PHP docs.
First line of comment = 1 line description
Lines 3..m = a longer description if you’d like
Lines m+1..n = the properties defined with @property, @property-read, @property-write    (the setters/getters with r/w, r, w status)
These property lines, like variable lines are simple:
@property-read <type> name  description
for example
@property-read string plugin_name the plugin name
This indicates a read-only property for the object.
4) phpDoc the methods
Like classes, but NetBeans is even better with the docs, you write the function first.   Then go before the function foo() line and type /**.   NetBeans will create the entire phpDoc template.   You update it to give it the “hints”.
This is something I use a LOT now and you’ll see why in a moment.   Here is an example from WPCSL_Settings add_section:
Old school:
* method: add_section
* does stuff
* params:
*     [0] - named array, blah blah
 * Create a settings page panel.
 * Does not render the panel.  Simply creates a container...
 * <pre><code>
 *   $mySettings->add_section(array('name'='general'));
 * </code></pre>
 * @param array $params named array of the section properties, name is required.
5) If your phpDoc property/variable type is a specific OBJECT then NAME THE OBJECT. 
For example:
class MP {

    * The WPCSL settings object, shortcut to the parent instantiated object.
    *  @var wpCSL_settings__mp
    private $wpcSettings = null;


Why I Am More Productive

Now here is why all these tips with phpDoc are useful and how I’ve slowly made my coding at least twice as efficient.
NetBeans defaults to having code hints and auto-fill turned on.   The cool part about this is it will do a few things like tell you when a required param is missing and flag the line as an error, the same way it does with blatant PHP syntax errors.    If you are creating some new code and you pause for a second with a partially written invocation then it will show you the possible options from a list of PHP functions, custom functions, or methods from objects you’ve phpDoc’ed properly.
Thus, I do something like this:
$this->wpcSettings->a   <pause>
It now shows me all the methods and properties in the WPCSL Settings Class that start with a in an in-place drop down list.
I cursor down to add_section and pause.
It shows me the full documentation on the method including my code example, the required parameters and more.
I press enter, it drops the completed method along with the first prototype in place, I cursor down to select from the various templates, for example if secondary parameters are optional, press enter and if fills out the entire code block.
I then modify the prototype to fill in my settings and I’m done.
If you do this right you can be ANYWHERE in your code as deep as you need to be.   You never have to go looking for the source, especially if you’ve written decent phpDoc comments.
I used to find myself split-screen looking at the source method or property code to see what it did or how it worked.    Now I spend time documenting the methods or properties in a verbose phpDoc comment and I never have to look at the code again.

Key Points

If you do NOT wrap everything inside a parent class it takes a lot longer to pop up the help.
If you just use the lazy @property object $myvar (or ‘mixed’) syntax you do not get to see all of the methods whenever you newly instantiated object is referenced by the variable name.
If you use things like public, private, setters, getters and use the matching phpDoc elements like @property-read  then NetBeans warns you if you do something illegal like try to directly SET that property.

A Day Older, A Day Smarter

I know some of you probably had productivity helpers like this while at Cyber Sprocket, but if I had known then what I know now I’d have been insisting that we all learn and properly implement phpDocs as our commenting standard.
An as you all know the other “freebie” with this is I could easily generate a full HTML (or markdown) site with all the classes, methods, and properties of any plugin with a few short commands.   I’ve not done that yet but will play with that sometime in the near future.    I need to figure out how to bake it into WordPress content at but I think it would be cool to have an entire plugin + wpCSL documented in an easy-to-browse format on the web.
Posted on

Speed Coding With phpStorm and WASD Keyboards

WASD Keyboard In Action

I’ve been coding a LOT more than usual over the past 3 weeks.    So much so that I’ve started having issues with my wrist, likely early onset of carpal tunnel which I would prefer to avoid.    I did a few things today to help offset that.

WASD Keyboard

The first was to buy an 87-key CODE keyboard from WASD.   This allows me to move my mouse a lot closer to “center” on my desktop.  Since I rarely use the numeric keypad or media keys, this is a good trade-off.  “Cut off” the numeric keypad and make the keyboard a lot narrower.   I’m not sure if I like the old-school clackety-clack of the Cherry MX Brown switches, but it has a great feel so I may get used to it.     Great backlighting as well.

WASD Keyboard In Action
WASD Keyboard In Action

One downside that I’ve already discovered is that the CTRL key through ALT key on the left side are more than a half-key position to the left of my old keyboard.  That makes the “reach” for CTRL-V (paste) keystrokes further apart than I like.    On the plus side, the full size / full travel keys have me looking down to validate my keystrokes far less often.  Overall I feel like I am typing much more quickly on this keyboard.  Amazing how much the tactile feel makes a difference in that regard.

New keyboard, less right-wrist travel especially for the mouse.   With another service launch coming this fall I expect a lot more coding; hopefully this change will eliminate the potential for carpal tunnel.

phpStorm Tricks

The other thing I did when getting the new keyboard, mostly due to changes in the keys that OSX recognizes, is setup some keyboard shortcuts in phpStorm.    I also learned some neat shortcuts I need to add to my daily routines.  Here are two of the most productive shortcuts that have my hitting a LOT fewer keys.

^Y = delete a line

This is going to save me from the old-habit ctrl-left-arrow , ctrl-shift-right-arrow, delete keystroke.   8 keystrokes down to 2.  Wish I discovered that one long ago.

Live Templates

This is HUGE.  Why didn’t I know about this 2 years ago?   What is a live template?   It can be a lot of things, but my simple version is using it as a permanently-saved copy & paste buffer for text I type frequently, especially during debugging.

What this does is sets up an auto-complete hint when you type in certain snippets of text (abbreviations).    For example, I have an echo statement I use when doing “quick & dirty debugging” in phpStorm.  It is faster than xdebug and all that complexity.    I have been manually typing in this long echo statement for years, something like echo “====== ” . get_class() . ‘::’ . __FUNCTION__ . “<br/>\n”;

I highlight that code, and select “Tools/Live Template”.    I then assign a shortcut, in my case I chose ‘ecof’ so it does not conflict with other PHP auto-complete hints.   Now I can simply type ecof-tab in phpStorm and it will auto-complete the line , replacing ecof with the entire echo statement above.

Cool, right?!


Now if phpStorm would just fix their newly-introduced “feature” in version 9 so I can get back the extra keystrokes I have to type every time I end a phpDoc comment line with a period (<sarcasm>which NEVER happens </sarcasm>) and they decide to auto-complete that as “.@deprecated”.


Coding Smarter…

Way less typing.  Faster code.  Less carpal tunnel.

I call that a win for today.


Posted on

Finding WordPress Programmers

WordPress Developer Banner

I am on a quest to find good programmers that are well versed in WordPress.   After speaking with multiple investors it is obvious that to bring Store Locator Plus to the next level I need to have talented self-sufficient staff.    I need to “up the game” from part-time support and coding positions to a senior-level PHP/WordPress expert that can be my “right hand man” when I’m not available.   This is especially important as my new media entertainment company is getting a lot of interest and starting to command more of my time every week.

The quest for a WordPress programmer is on.

Seeking :  Senior WordPress Programmer

Only apply for the position if:

  • You are an INDIVIDUAL, not a company and not an individual representing a company.
  • You have hands-on WordPress theme or plugin coding experience.
  • You write and speak English fluently.

Key skills I am seeking:

  • Well versed in WordPress coding.
  • Understand hooks and filters and have experience implementing them.
  • Possess extensive WordPress theme and/or plugin development experience.
  • Utilize proper object-oriented methodologies in their PHP implementations.
  • Use version control, git preferred, and comment documentation in phpDoc format.
  • Know and adhere to WordPress Core coding standards.

I will give preference to applicants that are geographically closest to Charleston SC USA.   Communications improve with fewer time zone differences.   They are even better when we can meet over coffee or beer on a routine basis.

Where I’m Looking

Rather than use my usual “go to” sources to find local programmers or low-to-mid-range programmers, I decided my current needs are best served by scouring the WordPress community for people that are going to be a better fit and require little training.   The usual suspects like Elance and Craigslist have failed to produce quality applicants in the past.  I’m going to completely forgo Elance as I don’t need to be spammed with 300 applicants that don’t read the requirements and are programming sweat-shops in India or some other low-cost/low-quality production shop.    (No hate mail please, I know they are not ALL like that but in my experience 9.5 of 10 of responses on these types of site are EXACTLY that).

Code Poet : WordPress Developers on G+

Code Poet links directed me off the site in fairly short order and landed me in the WordPress Developers Google group.  This is a discussion group about all kinds of WordPress “codish” topics.   There is a jobs section.  Not sure how much traffic it gets.  We’ll see.

Read my “seeking WordPress/PHP developer” post.

WordPress Developers on G+
WordPress Developers on G+

WP Hired

Free listings, quick and easy to setup.   You can upgrade to 30 day listings for $60/month.  I would post the job listing, but it takes a bit of time to be approved and listed.   They do allow for formatting of your listing and will link to your site and social media accounts.  That is a nice feature.  Not sure about the volume of traffic though.

Another free listing site that is WordPress-centric.  Requires some basic HTML if you want to format the listing.  Another waiting period so no links to that posting to see how it looks.

Jobs WordPress Net
Jobs WordPress Net
Posted on

Senior WordPress Plugin Developer Wanted

Evil Genius banner

Join Charleston Software Associates

Charleston Software Associates (CSA) is the company that has created the popular Store Locator Plus WordPress plugin.   The plugin is running on an estimated 45,000 sites and has 5,000 registered users of the premium add-on packs. CSA is a single-man operation based in Silicon Harbor, aka Charleston SC USA.

The Agenda

It is time to take the company to the next level.   I need a “right hand man” to help me drive Store Locator Plus quality and presentation up a notch.     Once we are don a re-tooling of WordPress to create a full-blown SaaS Store Locator Plus implementation is on the agenda.

If you’re up for a challenge and want to create something cool with WordPress, this is your chance.

Your Skills

  • Well versed in WordPress coding.
  • Understand hooks and filters and have experience implementing them.
  • Possess extensive WordPress theme and/or plugin development experience.
  • Utilize proper object-oriented methodologies in their PHP implementations.
  • Use version control, git preferred, and comment documentation in phpDoc format.
  • Know and adhere to WordPress Core coding standards.

The “geek check list”:

  • PHP
  • CSS
  • HTML
  • MySQL
  • jQuery
  • JavaScript
  • git

Bonus points:

  • Bitbucket
  • Grunt
  • VirtualBox
  • Vagrant
  • phpStorm
  • SmartGit
  • Selenium IDE

You Are A Fit If…

  • You are an INDIVIDUAL, not a company and not an individual representing a company.
  • You have hands-on WordPress theme or plugin coding experience.
  • You write and speak English fluently.

I will give preference to applicants that are geographically closest to Charleston SC USA.   Communications improve with fewer time zone differences.   They are even better when we can meet over coffee or beer on a routine basis.

Your Reward

This is my “first man on board” position.   That role will grow to be the “director and main man” over the coming months.   As the company grows the underlings will be under your control.   You will help set the technical direction and future release features.

The position will start at 20-30 hours per week through the end of 2014 as we build the relationship, you learn the code, and we get things organized.    By the time January 2015 gets started the goal is to make this a full time gig.

You tell me what your compensation should be.    I will do my best to make it work.   At the start you will be serving in a contractor/freelance role.   Once we start building the team this can transition to an employee role if that fits your needs.

Contact Me with your introduction.  When the dialogue begins you can email me your resume if you have one prepared.


Posted on

WordPress Development Fresh Start with Vagrant and Grunt

Banner Vagrant Cloud WP Dev Kit Box

HP finally did it.  They came out to replace a system board in my laptop and half of my files on my drive are corrupted.  Restoring the 70GB of corrupt files from the local USB3 backup will take some time and I am not 100% confident in the reliability of this system.   With 48 hours of downtime I decided it would be best to push forward with my Vagrant and Grunt setup for the WordPress Development Kit I’ve been working on.

Employing Vagrant

I am using VirutalBox and Vagrant to build a series of base boxes on which to layer my development environment.  Unlike most base boxes that are plain vanilla OS installs that then use provisioners to install all the software layers on top of the OS, my custom base boxes are going to be installed with all the base tools I need to develop WordPress plugins using my WordPress Development Kit tools.


Because it is far faster to download a compressed virtual machine image with most of my stuff installed  than to download a very similar image with no tools then have Vagrant go and download  a few dozen install kits.   Sure, the standard method is more flexible and ensures everything is up-to-date, but that is not what I am trying to accomplish here.    I am building a “fast start” box that has most of what you need pre-installed in a known environment.

I also want to have a method to deploy new virtual boxes with everything in place on my OS/X system, a different laptop, or even a cloud-based server the next time my HP laptop is smoked.  Which will probably be tomorrow.      As I’ve found, restoring a large image even from a local USB3 drive is not a quick process and it is not foolproof.   Especially when going from a Windows 8.1 based backup and restoring on an OS/X system that has not been patched or updated in 8 months.


Since I already have Vagrant installed and have a published base box I am able to get started quickly.   Once Vagrant is installed I only need to set my Vagrantfile, a script that tells Vagrant what to do, to pull down the base box from the URL I have published on Vagrant Cloud:

  • Create a folder on my host system named “C65 WP Devkit  Box Setup”.
  • Create the Vagrantfile, in that directory with the pointing to charlestonsw/centos6.5-wordpress-dev-kit-base-box.
  • Open the command line for Windows and go to that C65 WP Devkit Box Setup directory.
  • Run the vagrant up command.
My new Vagrantfile:

# -*- mode: ruby -*-
# vi: set ft=ruby :

# Vagrantfile API/syntax version. Don’t touch unless you know what you’re doing!
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| = "charlestonsw/centos6.5-wordpress-dev-kit-base-box"
config.vm.provider "virtualbox" do |vb|
vb.gui = true


When you boot the WordPress Dev Kit Base Box with Vagrant you will find that the full CentOS GUI is active. You can login to the GUI using the standard vagrant username with a password of vagrant.

WordPress 3.9

You will find a Firefox icon on the menu bar. Opening Firefox will open the http://localhost/ URL which brings up the local copy of WordPress 3.9 that has been installed.

MySQL for WordPress

The MySQL database has been configured for WordPress.

Database name: wordpress
MySQL User: vagrant
MySQL Password: vagrant

NetBeans 8.0

NetBeans 8.0 has been installed with the PHP and HTML 5 support packages.   NetBeans is a great no-cost IDE that I have found to be very useful for editing structured WordPress PHP code.   Write your code using an object oriented design and add a good amount of phpDoc commenting and NetBeans becomes a coding power tool for WordPress plugin coding.


Firefox is installed along with several add-on packs that I use for every day code management and development.  It includes Firebug to look at JavaScript, CSS, and HTML construction.   Selenium IDE is included which allows me to download and execute my web-interface based test scripts for Store Locator Plus.   LastPass is installed to provide unique long-string passwords to all of my web services.

WordPress Development Kit

My command line WordPress Development Kit is installed on the system under the vagrant user home directory in ~/wp-dev-kit. This comes with the basic Grunt build tasks I use to manage my plugins. While you can edit the ~/wp-dev-kit/grunt/plugins.json file and configure this for your site it is recommended that you create a fork of my WordPress Development Kit on the Bitbucket site and work from your forked repository. I would remove the wp-dev-kit directory with rm -rf and clone your forked copy into the same location.

The easiest method for cloning a public repository is to use git clone with the https repository path. If you have a private repository you may want to create a SSH key pair by going to ~/.ssh and running ssh-keygen. The key will need to be added as an authorized SSH key in your Bitbucket account access management list.  Since I will be pushing and pulling content from my various Bitbucket git repositories I will use this method when setting up my clone of the WP Dev Kit Basic Box.

Bitbucket HTTPS Path
Bitbucket HTTPS Path

Similar methods can be employed with Github repositories.

Preparing For Development

These are elements that will eventually go into a provisioner setup for the Vagrant box, assuming that at least one of the Vagrant provisioning services can hand user prompts and communication with third party services.

Create Your SSH Key

This will make it easier to push & pull content from your repositories.

cd ~/.ssh
xclip -sel clip &lt; ~/.ssh/
Setting A Vagrant SSH Key
Setting A Vagrant SSH Key

Login to your Bitbucket account, go to my account / access management, add the copied SSH key.

Bitbucket Add Vagrant Key
Bitbucket Add Vagrant Key

 Configure Your Git ID

git config –global “Lance Cleveland”
git config –global

Add SmartGit

I like the GUI interface that SmartGit provides over the git command line and gitk branch rendering.  I find SmartGit to be twice as efficient for my method of work flow over the built-in IDE and command line, so I always install this next and clone my base projects like the WP Dev Kit and my Selenium IDE scripts.   Today I am using the SmartGit 6 beta release as I find the project grouping and new interface design to be a big help in managing my projects.

SmartGit UI
SmartGit UI

I immediately setup SmartGit and clone my Selenium IDE repository so I can complete the next step with a script.

SmartGit Bitbucket Setup
SmartGit Bitbucket Setup

Complete The WordPress Install

Open Firefox and go to http://localhost/

Enter the WordPress local site information for your test site.  I use my Selenium IDE new site install script to handle this for me.

Selenium IDE setting up a  new WordPress install.
Selenium IDE setting up a new WordPress install.

Ready To Go

Now my system is ready to go.   I can start cloning my plugin code repositories into the ./wp-content/plugins directory, edit code with NetBeans, commit changes with SmartGit, and publish to my server or the WordPress plugin directory using my Grunt scripts.

With the current configuration it takes me 15 minutes to pull down a new clone and get the box booted then 5 minutes to install and configure SmartGit, clone my repository, run the WordPress install script, and fetch my first plugin repo.   20 minutes from “nothingness” to writing code.    With a local .box file on my system that time is cut down to about 8 minutes by avoiding the 1.5GB download of the box.

Not bad.

Now on to the code…

Posted on

WordPress Dev Kit : Legacy Publisher

WordPress Plugin Directory Banner

This article is about my legacy publishing process for development WordPress plugins and themes.   It is my workflow and it is far from perfect.  It will evolve over time and I am in the midst of making several big changes using new tools to assist in the process.   To get some background on the process you may want to follow along with the WordPress Workflow and WordPress Development Kit threads on my blog.

My Setup

My WordPress development is fully contained in a VirtualBox running CentOS 6.5 with a full GUI interface.   I am working on building an distributing some Vagrant boxes that will help others replicate the process.  My base CentOS 6.5 GUI box is online but is not a full setup… yet.   You can read about Vagrant in the WordPress Workflow thread.

My plugin development environment consists of a standard WordPress production build (3.8.1 today) with the typical wp-content/plugins subdirectory.  On my development system I work directly inside of these directories.  It provides instant access to the modified code without running a repetitive series of push/pull commands to move stuff into a “ready to review” state.    I find this configuration to be far more efficient and rely on semi-intelligent scripts to help me “weed out” the development environment when building the production-ready kits.    As a last step before production I have a test box on a remote server where I install the production releases as a clean last-minute sanity check.  This will migrate to a Vagrant-based “clean production simulator” to provide more robust testing.

How does my “inline production” setup look?

The Build Scripts

The top-level build scripts go in my ./wp-content/plugins directory.   That is not exactly accurate.   I should say that symbolically linked file pointers (symlinks for Linux geeks… or shortcuts in Windows lingo) go in that directory.   This includes the makezip, update_wrepo, exclude and common files that are part of the legacy/publisher section of the new WP Dev Kit I’ve published on Bitbucket.

Plugin Assets

Within each plugin subdirectory I create an assets subdirectory.  This is where my “build and production helpers” go.   My scripts specifically avoid this directory when packaging the “for consumption” products.  Within this directory I currently store things like raw image assets that typically get pushed the WordPress Plugin Directory, a full copy of the WordPress svn repository for any plugins published there, and other “goodies” I need for production that I do not distribute.  This is where my new Grunt and other build helpers will go.

Published Files Store

There is a separate directory under my home directory, ~/myplugins, where the published files go.   This helps keep my production files separate from the main plugins.  This will eventually change as I improve and streamline the process.

NetBeans “Push” Project

I also have a special directory under my home directory where I keep non-WordPress NetBeans projects.   One of those projects is a private project named “csa_licman”.  One of the many things this project does, which will also be changing, is sync any changes I make in the subdirectories of the csa_licman project up to my live server.  I use this to “publish” my premium add-ons to my live server.    I will not cover that part of the project here or the NetBeans automated FTP push setup.

You can find details on getting NetBeans projects to watch a directory and FTP files elsewhere on the NetBeans site.  I will be changing this complex part of the system to automated Grunt processing in a later revision to the WP Dev Kit.    For now you can keep the myplugins directory and manually FTP files from there to any private directories.

Keep in mind that anything going to the public WordPress Plugin Directory will be handled via the legacy script.   The NetBeans push project is only for my premium add-on packs that are not hosted in the WP Plugin Directory.

My tool kit currently consists of:

git – for managing my code repository.  I find it faster and lighter than svn.

svn – solely for publishing to the WP Plugin Directory.

smartgit – my GUI to help me cheat with git commands, I am MUCH faster with the GUI.

NetBeans – my IDE setup specifically for PHP development with heavy use of phpDoc hints in my code.

Firefox with Firebug – my test and development browser because Firebug is the easiest-to-use development tool set.

command line with Bash – the Linux command line for executing my Bash scripts, most of this should work on OSX as well.

Using The Legacy Publisher

Here is how I setup and use the legacy publisher scripts in my setup.   I call them “legacy publisher” scripts as I am learning Grunt and working toward a more intelligent processor.  The legacy publisher is based on simple Bash scripts which can be complex to configure and extend.   Grunt provides a managed system that will fetch various plugins to do a lot of cool stuff that would take me far to long to replicate in Bash.    Why re-invent the wheel?

After I get my new dev box setup and I have WordPress up-and-running and my development plugins in place under the wp-content plugins directory I attach my legacy publisher kit.   I am not going to cover the NetBeans push setup under csa_licman though you will see it referenced in the shell scripts.   Always answer “n” to “publish to live server” when running any of the legacy scripts and you will not have issues as that part of the script will not be executed.

Under my login I use git to fetch the WP Dev Kit from Bitbucket,  setup my published files directories, I then link the legacy publisher kits into my WordPress plugin directory:

cd ~
mkdir myplugins
git clone ./wp-dev-kit
cd /var/www/wpslp/wp-content/plugins
ln -s ~/wp-dev-kit/legacy/publisher/*

I am now ready to use the legacy kit to build my production zip files and publish them by hand to my server or use to push them to my WordPress Plugin Directory listing.

Simple Self-Hosted Plugins

My premium add-on plugins are the simplest setup for this environment.   Once I have my legacy publisher scripts in place I can create my base plugin files right in the plugin directory.   I edit my readme and php files, test locally, and when ready I publish them in one step with the makezip command.  Since I have a NetBeans automated push project I can answer “y” to the publish to live server question and get the files over to my server.  If you do not have this setup you can answer no and manually FTP the files in ~/myplugins to your final destination.

cd /var/www/wpslp/wp-content/plugins
./makezip slp-enhanced-results
Legacy Publisher Makezip Example
Using legacy publisher scripts to create a production zip file.

WordPress Hosted Plugins

WordPress hosted plugins, such as the Store Locator Plus plugin, require a bit of extra work to get them ready for production.    After the initial setup is in place I can update the production release using the script.    In this setup I use the assets subdirectory to assist in the production.   It is where the svn repository lives that gets updates to the WordPress servers. 

Store Locator Plus Plugin Development Folders
Store Locator Plus plugin development folders.

I start with my plugin directory in place and build the setup necessary for the legacy script to publish to WordPress:

cd /var/www/wpslp/wp-content/plugins
cd store-locator-le
mkdir assets
echo '<?php // Silence is golden.' > index.php
svn co '' svnrepo
mkdir public

My plugin is now ready for publication. I go to the wp-content/plugins directory and run and answer the prompts whenever I am ready to push to the WordPress plugin directory. The process also build a local zip file in the ~/myplugins directory so I can keep a copy on my servers.   The script will update trunk, create the version branch and even try to clean up any tags or branches if a push of the same version has failed previously.

WP Directory Marketing Assets

Getting asset files into the WordPress repository is also part of the script.   This is the preferred method for storing your plugin banner and screen shots as it lists them on the WordPress site without filling up the .zip distribution that goes to the client.  With the legacy publisher it is easy, though a bit of a manual process.   I store my banner and screenshot files in the ./assets subdirectory (note to self: should create a wp_marketing_images subdir).  Since the assets directory is never part of the published file set they are ignored.   To add assets to the WP Plugin Directory publication I create an assets directory under the svnrepo, copy over the image files I want, and run svn up from the svnrepo directory.

The Scripts

The following scripts are included in the legacy/publisher directory in my WordPress Dev Kit:

Setup common Bash variables that the other scripts use to run.


The list of directories and files to be excluded when zipping up the plugin directory.

The script that packages up the plugin directory.   Currently with some extra “cruft” to rename some of my plugin directories to a different zip file name when doing the “publish to live server” logic.

Runs makezip, unpacks the zip file into the assets/public directory to ensure a clean copy of the plugin, copies to svn repository trunk and branches to push to the WP Plugin Directory.

Posted on

WordPress Workflow : Automated Virtual Box Creation

PuPHPet Vagrant Puppet Banner

I am into my first full day back after WordCamp Atlanta (#wcatl) and have caught up on most of my inbox, Twitter, and Facebook communications.   As I head into a new week of WordPress plugin production I decided now is as good a time as any to update my work flow.

I learned a lot of new things at WordCamp and if there is one thing I’ve learned from past experience it is DO NOT WAIT.   I find the longer I take to start implementing an idea the less chance I have of executing.

My first WordCamp Atlanta 2014 work flow improvement starts right at the base level.   Setting up a clean local development box.   I had started this process last week by manually configuring a baseline CentOS box and was about to setup MySQL, PHP, and all the other goodies by hand.  That was before I learned more about exactly what Vagrant can do.   I had heard of Vagrant but did not fully internalize how it can help me.  Not until this past weekend, that is.

My Work Environment

Before I outline my experience with the process I will share my plugin development work environment.

  • Host System: Windows 8.1 64-bit on an HP Zbook laptop with 16GB of RAM with a 600GB SATA drive
  • Guest System: CentOS 6.5 (latest build) with 8GB RAM on an Oracle VirtualBox virtual machine
    • Linux Kernel 2.6.32-431
    • PHP v5.4.23
    • MySQL v 14.14 dist 5.5.35
  • Dev Took Kit: NetBeans, SmartGit, Apigen and phpDoc, MySQL command line, vim
HP Zbook Windows 411
My Development System laptop config.

While that is my TYPICAL development environment, every-so-often I swap something out such as the MySQL version or PHP version and it is a HUGE PAIN.    This is where Vagrant should help.  I can spin up different virtual boxes such as a single-monitor versus three-monitor configuration when I am on the road or a box with a different version of PHP.     At least that is the theory anyway.   For now I want to focus on getting a “clean” CentOS 6.5 build with my core applications running so I can get back to releasing the Store Locator Plus Enhanced Results add-on pack this week.

Getting Started With Vagrant

The Rockin’ Local Development With Vagrant talk that Russel Fair gave on Saturday had me a bit worried as he was clearly on the OS/X host and the examples looked great from a command line standpoint.  Being a Linux geek I love command line, but I am not about to run virtual development boxes in in a VirtualBox guest.   Seems like a Pandora’s box to me… or at least a Russian doll that will surely slow down performance.   Instead I want to make sure I have Vagrant running on my Windows 8.1 bare metal host.    That is very much against my “full dev environment in a self-contained and portable virtual environment” standard, but one “helper tool” with configurations backed up to my remote Bitbucket repository shouldn’t be too bad, as long as I don’t make it a habit to put dev workflow tools on my host box. Yes, Vagrant does have a Windows installer and I’m fairly certain I won’t need to be running command-line windows to make stuff work.   If I’m running Windows I expect native apps to be fully configurable via the GUI.  Worst case I may need to open a text editor to tweak some files, but no command line please.

Here is the process for a Windows 8.1 install.

  • Download Vagrant.
  • Install needs to be run as admin and requires a system reboot.
  • Ok… it did something… but what?   No icons on the desktop or task bar or … well… anywhere that I can find!

Well… sadly it turns out that Vagrant appears to be a command line only port of the Linux/OSX variants.    No desktop icons, no GUI interface.   I get it.  Doing that is the fast and easy process, but to engage people on the Microsoft desktop you really do need a GUI.    Yes, I’m geek enough to do this and figure it out.   I can also run git command line with no problem but I am FAR more efficient with things like the SmartGit GUI interface.

Maybe I’m not a real geek, but I don’t think using command line and keyboard interaction as the ONLY method for interacting with a computer makes you a real techie.    There is a reason I use a graphical IDE instead of vim these days.    I can do a majority of my work with vim, but it is FAR more efficient to use the GUI elements of my code editor.

Note to Vagrant: if you are doing a windows port at least drop a shortcut icon on the desktop and/or task bar and setup a Windows installer.   Phase 2: consider building a GUI interface on top of the command line system.

It looks like Vagrant is a lower-level command line tool.   It will definitely still have its place, but much like git, this is a too on which other “helpers” need to be added to make my workflow truly efficient.  Time to see what other tools are out there.

Kinda GUI Vagrant : PuPHPet

Luckily some other code geeks seem to like the idea of  GUI configuration system and guess what?   Someone created a tool called PuPHPet (which I also saw referenced at WordCamp so it must be cool)  and even wrote an article about Vagrant and Puppet.   Puppet is a “add on”, called a provisioner,  to setup the guest software environment.

PuPHPet is an online form-based system that builds the text-file configuration scripts that are needed by Vagrant to build and configure your Virtualbox (or VMWare) servers.   It is fairly solid for building a WordPress development environment, but it does mean reverting back to CentOS 6.4 as CentOS 6.5 build scripts are not online.     Though I am sure I can tweak that line of the config files and fix that, but that takes me one-step away from the “point and click” operation I am looking for.

Either way, PuPHPet, is very cool and definitely worth playing with if you are going to be doing any WordPress-centric Vagrant work.

PuPHPet Intro Page
The PuPHPet online configuration tool for creating Vagrant + Puppet config files.


Puppet Makes Vagrant and PuPHPet Smarter

Now that I have Vagrant installed and I discovered PuPHPet I feel like I am getting closer to a “spin me up a new virtual dev box, destroy-as-desired, repeat” configuration.  The first part of my workflow improvement process.   BUT…. I need one more thing to take care of it seems… get Puppet installed.   I managed to wade through the documentation (and a few videos) to find the Windows installers.

Based on what is coming up in the install window it looks like the installer will roll out some Apache libs, ruby, and the windows kits that help ruby run on a windows box.

Puppet Install Licenses
The Puppet installer on Windows.

Again, much like Vagrant, Puppet completes the installation with little hint of what it has done.    Puppet is another command line utility that runs at a lower-level to configure the server environments.   It will need some of the “special sauce” to facilitate its use.     A little bit of digging has shown that the Puppet files are all installed under the C:\Program Files (x86)\Puppet Labs folder.    On Windows 8.1 the “Start Menu” is MIA, so the documentation about finding shortcuts there won’t help you.    Apparently those shortcuts are links to HTML doc pages and some basic Windows shell scripts (aka Batch Files) so nothing critical appears to have gone missing.

The two files that are referenced most often are the puppet and facter scripts, so we’ll want to keep track of those.   I’ll create a new folder under My Documents called “WP Development Kit” where I can start dumping things that will help me managed my Windows hosted virtual development environment for WordPress. While I’m at it I will put some links in there for Vagrant and get my PuPHPet files all into a single reference point.

WP Dev Kit Directory
The start of my WP Dev Kit directory. Makes finding my PuPHPet, Vagrant, and Puppet files easier.

Now to get all these command line programs to do my bidding.

Getting It Up

After a few hours or reading, downloading, installing, reading some more, and chasing my son around the house as the “brain eating dad-zombie”, I am ready to try to make it all do something for me.    Apparently I need to use something called a “command line”.  On Windows 8.1.

I’m giving in with the hopes that this small foray into the 1980’s world of command line system administration will yield great benefits that will soon make me forget that DOS still exists under all these fancy icons and windows.   Off to the “black screen of despair”, on of the lesser-known Windows brethren of the “blue screen of death”.     Though Windows 8 tries very hard to hide the underpinnings of the operating system, a recent Windows 8 patch and part of Windows 8.1 since “birth” is the ever-useful Windows-x keyboard shortcut.   If you don’t know this one, you should.   Hold down the Windows key and press x.   You will get a Windows pop-up menu that will allow you to select, among many other things, the Command Prompt application.

If you right-click on the “do you really want to go down this rabbit hole” confirmation box that comes up with the Command Prompt (admin) program you will see that it is running C:\Windows\system32\cmd.exe.     This will be useful for creating a shortcut link that will allow me to not only be in command mode but also to be in the “source” directory of my PuPHPet file set.    I’m going to create a shortcut to that application in my new WP Development Kit directory along with some new parameters:

  • Search for cmd.exe and find the one in the Windows\system32 directory.
  • Right-click and drag the file over to my WP Development Kit folder, selecting “create shortcuts here” when I drop it.
  • My shortcut to cmd.exe is put in place, but needs tweaking…
  • Right-click the shortcut and set the “Start in” to my full WP Development Kit folder.

Now I can double-click the command prompt shortcut in my WP Development Kit folder and not need to change directory to a full path or “up and down the directory tree” to get to my configuration environment.

Running Vagrant andn Puppet via PuPHPet Scripts
Running Vagrant andn Puppet via PuPHPet Scripts

A few key presses later and I’ve managed to change to my downloaded PuPHPet directory and execute the “vagrant up” command.   Gears starting whirring, download counters started ticking, and it appears the PuPHPet/Vagrant/Puppet trio are working together to make something happen.  At the very least it is downloading a bunch of stuff from far away lands and filling up my hard drive.   Hopefully with useful Virtualbox disk images and applications required to get things fired up for my new WordPress dev box.

We’ll see…

Link Summary

Posted on

Making GitHub Wiki Docs From PHP Source

I’ve been using NetBeans to write my PHP-based WordPress plugins and have found that well crafted PHPDoc comments make a notable difference in the efficiency of my coding.   I’ve written a post-or-two about that and find the auto-fill features to be very helpful.    I have also noticed that much of the WordPress core also follows PHPDoc conventions, so using PHPDoc is a good way to comment your WordPress plugin code IMO.

The other tools I use frequently are GitHub with SmartGit.   While git had a steeper learning curve than subversion, I much prefer the lighter “differential data” standard of git as well as the distributed repository concept.   Both just “feel” smarter.   The next logical step from tracking code commits and issues with GitHub was finding a home for my code documentation.     I really didn’t want to manually great web pages from the PHDoc raw HTML.  I also didn’t want to write a plugin to read PHPDoc to get the content into my website, so I went on a quest to find the tools needed to publish my PHP comments right on the GitHub wiki pages.    After a long search I finally found the pieces of the puzzle I needed to go from PHP comments to GitHub wiki pages with limited effort.  The process is outlined below.

Clone Your GitHub Wiki Pages

  • Go to your GitHub project and look for the Wiki tab. If you do not have it, especially for an older project, you may need to enable “pages” in the repo settings at GitHub.
  • Under the Wiki tab is a sub-tab for “Git Access”. It has the WIKI repo URL, which will automatically be attached to the parent project under the wiki tab.
  • Clone this to a new directory on your dev box.
  • (BTW, this step is optional, this is just how I opted to do this, keep the docs OUT of my main code repo).

Setup/Build The PHPDocMD Tool

$docmdDir = dirname(<strong>FILE</strong>);
// Potential composer autoloader paths $paths = array( $docmdDir . '/../src/PHPDocMD/Parser.php', $docmdDir . '/../src/PHPDocMD/Generator.php', $docmdDir . '/../src/Twig/lib/Twig/Autoloader.php', );
foreach($paths as $path) { if (file_exists($path)) { include $path; print "including $path\n"; } }
// Everts crappy option parser.

These code edits are necessary because the tool is not refined yet. It was clearly setup for the developer’s system which has Twig installed and a vendor autoloader file that is not in the git repo. Not a big deal, easy enough to get around if you follow the steps here.

BTW, that last comment is his, not mine. I left if there so you know where to stop the edit.

Use PhpDoc & PHPDocMD

You may want to symlink that phpdocmd to your /usr/bin directory so you don’t have to type the full path every time, but now you just need a few steps to create GitHub Wiki compatible doc files:

# phpdoc -t . -d .

That creates the structure.xml file needed to generate the MD files.

Then run this command:

# phpdocmd ./structure.xml <path to your github WIKI project>

Now your GitHub Wiki Docs project should be full of MD files that reflect your code PHPDocs. Just push your GitHub Wiki files back to the GitHub server.