Greg Boone

Tag: WordPress

Leaving 18F

Today was my last day at 18F, the startup-like agency inside the U.S General Services Administration I joined back in September 2014. When I joined I wrote: “Working with a team of talented individuals to create a more open, transparent, and accessible government is a cause close to my heart.” That’s still true. It’s also true that, four years in, nobody has used their political clout or tenure to shut it down as was foretold to me by a former colleague.

It might be easy to see my leaving as politically driven by the administration change. It is not. While there are more politically appointed individuals overseeing 18F and TTS’s work than when I started, any notion that the organization was taken over by the White House, or that they are now expected to be White House loyalists, is overblown. We took an oath to protect and uphold the Constitution and that includes the 14th Amendment which promises equal protection under the law. No American should see their government services degraded just because the people who deliver it happen to disagree with the people setting the policy. There’s a broader academic argument but it’s not for this post.

I’m leaving because my term is almost up and when I look back on it, it’s kind of staggering how much I’ve gotten to work on over the last 3 years, 4 months, and 9 days at 18F.

I was part of the team that figured out what the 18F website needed to do for people and rebuilt it basically from scratch to better serve the agencies trying to work with us. I didn’t do much (any?) of the building, but my team knocked it out of the park.

The homepage of 18f.gsa.gov
The 18F website

One of the first projects I helped with was our work supporting the US Extractives Industries Transparency Initiative (now Natural Resource Revenues Data). I helped the team write and plan their communications and in the process learned everything I wanted to know about natural resources revenues from federal lands but was too ashamed to ask. I also got to watch a team think deeply about who needed this information, why, and how they wanted to access it.

The revenuedata.doi.gov homepage
NRRD, formerly EITI

I helped the team that implemented the United States’ first open data law write about how they got every federal agency in the government to report spending data in the same way. It’s called the DATA Act, and it was a massive undertaking. See their work: https://beta.usaspending.gov/#/ and learn more about it: https://18f.gsa.gov/tags/data-act/

The homepage of beta.usaspending.gov
The DATA Act website

More recently I worked with the cloud.gov team build a Platform as a Service designed to comply with federal policy. It’s the first fully open source product to be authorized by FedRAMP. For the layperson reading this, it’s a big damn deal. FedRAMP is the federal cloud services equivalent to a boundary waters outfitter telling you to go with the WeNoNah canoe. You still need to decide if it’s right for you but it’s a strong endorsement.

The newly redesigned cloud.gov homepage
cloud.gov

I learned a lot about how government contracting works, enough to know that I’ll never come close to knowing everything. I scratched the surface working with the team behind CALC, a market research tool that helps contracting officers determine a fair market price for professional services.

The CALC homepage
CALC: On the surface it’s an acronym for Contract-Awarded Labor Category

And then there’s all the things that happened while I was at 18F. Even if I didn’t get to help build or write about them, it was inspiring to be on the same team as those folks.

One of our teams built the first web design system for federal teams.

The homepage for standards.usa.gov
The US Web Design Standards

I learned so much about SSL working on one of the teams that was in the room for the federal government’s HTTPS Everywhere policies. That team also put together a dashboard showing the fed’s compliance with those policies.

The pulse.cio.gov homepage
How the government is doing with it’s HTTPS commitments

Another team in the TTS umbrella organization manages the Digital Analytics Program, a standardized way for government agencies to run Google Analytics. That team created a data visualization of governmentwide analytics data. You can see not only how many people are accessing what pages, you can see what browsers they’re using and where the traffic is coming from.

The analytics.usa.gov homepage as captured on January 15, 2018
Public results of the digital analytics program

OMB published a governmentwide open source policy shaped by voices from across the government and the country. The Department of Education to created the College Scorecard, a tool my own cousin used in her college search. The FBI released the Crime Data Explorer, making otherwise hard to find data accessible and open. We worked with Code for America and the State of California to help the California Child Welfare system deliver better services to their constituents. And then we helped Mississippi do the same.

I could really go on and on.

The federal government employs some of the most talented individuals I’ve ever worked with. They’re motivated by honest and passionate service to the American public. That was what I signed onto when I joined in 2014 and, though many of the faces behind it have changed, that spirit remains.

As for me, I’m off to Automattic where I’ll continue working for a passionate, open source team helping WordPress.com customers have a great experience with a product I’m passionate about. WordPress helps people around the world tell their story, whether it’s an individual food blogger or a major newspaper.

What I learned setting up WordPress on cloud.gov

Since around June, I’ve worked on 18F’s cloud.gov product and this week marked my last quarter on the team. We end every quarter with a so-called “innovation and planning” sprint. The product managers do the planning and the team members do the innovating. Innovating in this context means working on parts of the product that will benefit users that aren’t part of the normal business work. I chose to work on improving the WordPress example app we maintain for our users.

If you’re not familiar, cloud.gov is a Platform as a Service built by federal employees and designed around the specific security and regulatory concerns federal agencies need to consider before they’re authorized to launch a web product. No matter how big or small, whether it has open data or national secrets, all information systems operated by the federal government are required to undergo some kind of evaluation against standards published by the National Institute for Standards and Technology (NIST). The result of this process is the granting of what’s called an “Authority to Operate,” or ATO. Basically, an ATO says that the system meets the requirements outlined by NIST and the agency has accepted any risks the system might present. If an agency runs several websites they end up with a lot of repetitive documentation for components that may be the same across each individual app. cloud.gov attempts to solve this problem by standardizing many of those common components so that the agency only has to worry about the parts of the application that serve their mission directly.

It’s a fully open source and based on the Cloud Foundry PaaS project. Compared to how I’ve launched and managed WordPress sites in the past it’s a pretty big shift in how to think about the product. The main shift is finding ways to not rely on the filesystem.

To do that means pushing your uploaded files straight to S3 or another cloud storage service. It also means session information needs to be stored in a cloud service like redis. Most of the example we cribbed from Cloud Foundry’s example WordPress app but due to slight differences in our infrastructure environment, we needed to make a few alterations. The most significant was the recommended plugin for connecting to S3. Cloud Foundry’s example used a more robust AWS plugin but one that required extra effort for us to connect to Amazon’s GovCloud environment. Using that plugin meant installing two plugins from WordPress and then writing and maintaining our own helper plugin to interface with them. Human Made’s plugin was a drop in plugin that already pulled credentials from the environment and was much simpler to configure for cloud.gov.

Getting this up and running reminded me of the work I did at CFPB getting their then-WordPress site — the last major WP site I worked on — into a stable, easily deployable production environment and how much easier that all would have been with cloud.gov at our disposal.

We configured WordPress very similarly to how cloud.gov arranges the pieces. Uploads were synced to S3 and we heavily cached the site — including the local session. The difference is that we spent weeks, maybe even months, writing and maintaining a Fabric project that could install plugins, update the themes, and manage the version of Core we ran in production and then getting our CI server, Jenkins, to automate the deployment of it all. We ended up with a well-functioning DevOps flow for consumerfinance.gov that didn’t require any of us to be physically around whenever someone needed a deployment to happen. All of that was good and important work, don’t get me wrong, we were rightly proud of what we did. The point is that a product like cloud.gov could have saved us a ton of time because a lot of that orchestration is done behind the scenes.

If we’d had a platform like cloud.gov to start from, we could have saved ourselves a lot of that work and focused on other things closer to our mission.

WordPress was the first open source project I ever worked with and the one that taught me how to be a professional developer. cloud.gov has the potential to make government web applications faster, more reliable, and more secure. The two of them together make up a giant stack of open source code. I’m glad I had a chance to bring these passions together.

Switching back to WordPress

I’ve been writing this blog as a Jekyll for quite some time now. There’s a lot I really do love about the idea of static sites, but also a lot I’ve cooled on. One of those things was the writing experience.

My first encounter with Jekyll was at CFPB and I briefly switched to Octopress while I was learning how it worked. At 18F, I decided it’d be prudent to eat my own dog food, as it were, and host my blog the same way we hosted the site I was managing, 18f.gsa.gov. It’s been three years on Jekyll now and while I love a lot about Jekyll and the paradigm of static sites, I’ve grown tied of the work I have to do just to publish a new post. I’ve written about this before and won’t repeat myself but I was hopeful that there would be a product, open source or otherwise, that would give all the advantages of static hosting with a writing and publishing experience that was just as simple and powerful. The fact is, there’s not.

And it turns out easy publishing on a trustable platform is all I really want.

Getting here meant I had to write a Jekyll plugin and a page to generate a WordPress eXtended RSS (WRX) file out of the old Jekyll site. Most of the work was done in the liquid page, except for custom fields which were filled in with the plugin. The only problem I’ve noticed so far was about 22 pages with no title that were in the WRX file — these were Jekyll paginator pages and the WRX file itself also generated as HTML 🤷‍♂️.

The Lasting Power of WYSIWYG

Jekyll has become one of my favorite things lately. At 18F we’re using it to power our website but also our Hub project which includes serving up snippets, our weekly team updates submitted by Google Form, as well as a tremendous amount of information that is a mix of pages restricted to our team and some that is public. The Hub uses Prose to allow people less comfortable with GitHub and Markdown to edit Jekyll pages with something closer to a What you See is What You Get (WYSIWYG) interface than a typical markdown document has. Prose is a great tool, and I’m not just saying that because we use it. But for many static sites haven’t quite gone far enough, and that’s okay.

Early adopters like static sites a lot. People who bought one of the first Blackberries or used WordPress in 2006, for example, might like static site generators a lot. People who like Markdown or other markup languages enjoy static site generators. And some appreciate the simplicity of configuration found in static sites, especially the lack of a database. For many people like me it is a refreshing focus on writing without the complications of The Admin UI that have plagued even the best CMS platforms.

An example of these complications? I recently helped my wife with some settings on her blog and was reminded how confusing the WordPress Admin can be. Where do you think you should go to set your front page to display a page instead of latest posts? Settings > General? Settings > Writing? Settings > Media? The answer: None of the above. It’s Settings > Reading. I guess when I think about it that makes sense, you’re changing a setting that changes the experience for someone reading your site.

At the same time, there are still some things that a CMS does really well that static site generators
lack
. At least to me, Jekyll’s simplicity is a feature that forces me to think about the value of, for example, a tag archive or automatic image formatting before implementing it. With a CMS these features are there waiting for you to use or extend. WordPress for example provides a really simple API to extend the WYSIWYG interface with ‘shortcodes.’ All of this comes in handy when you need to create a blog post with images floated left and right and center, or when building that tag archive (easy as it may
be
) means taking away time from publishing real content.

If I’m not a developer, needing to become one or hire one just to start writing a blog post is a pretty high barrier to entry. Feeling like I need to become one just to write a blog post is even higher. The reason I became a developer in the first place was that in 2006 when I needed to reboot my college radio station’s website WordPress was insanely easy to install and configure and gave us almost everything we needed (with the right theme and plugins), and in 2009 when I built the first version of HarmsBoone.org and International Underground I didn’t need to learn much beyond CSS and a few WordPress methods. When I eventually needed to know more it was still a fairly low barrier to entry and we always had a website that everybody could edit. In particular, Child themeing is particularly useful for learning WordPress on the fly.

Static sites, for all their simplicies and technical advantages, still have a pretty high barrier to entry, especially if you need to overcome the limitations GitHub pages puts on Jekyll sites. And to be fair, WordPress has significant (read: 8-10 year) head start over Jekyll plus the entire WordPress Core and Automattic teams nurturing the developer base.

Nevertheless, without lowering that bar and adding some of those features it will be really hard to get broader adoption among people who want a Just Start Writing Already. For many, logging in to the WordPress Admin and using the WYSIWYG either to write or to paste in copied text will always be preferable to editing monospaced text with strange formatting signals around it, even if there are buttons to help them out. (Let’s not belittle the bar-lowering power or Prose, Dillinger, and other Markdown helpers, though, for some they may be exactly the right tool.)

It will remain preferable even if they rely on a bookmark in their browser, or an icon on their desktop to get them to the admin screen. Clicking “Preview” will be preferable to navigating to running a shell command and then heading to localhost:4000 because what’s a localhost? What’s that colon all about? And what’s so special about 4000? And clicking “Publish” will definitely be preferable over committing a git workflow to memory.

These are problems Static Site Generators can solve, and part of what makes them beautiful is how they are malleable to each user’s needs. And if you put
a developer on the comms team
you’ll be able to build the site you need on the platform that works because you’ll ask your users what they need and how they work. If your users need to
copy and paste blog posts from Google Docs, give them that. If they want a WYSIWYG editor for writing and collaborating on posts, give them that. If the need the full WordPress UI, give them that. I’m not trying to sound flippant. Building a WYSIWYG on top of Jekyll would be a difficult problem, but it’s not
impossible
. Using Google Drive as a CMS will also take work, it’s not impossible. Building GUI applications to abstract away the command line is difficult, but not impossible.

There are hundreds of content management
systems
and static site generators operating on nearly every language in existence (including FORTRAN). And there are WordPress plugins for nearly everything imaginable at this point, and usually there are three of four of them to choose from. Your mileage will almost certainly vary from one solution to another but go with the solution that will make your content creators most comfortable.

rePress: Jekyll with a WordPress Frontend

Note: I’m not maintaining this open source project anymore. There was a pretty cool reception to it and I didn’t have time to maintain it for just myself. I still think it’s a good idea, though. 🙂

About five months ago I left the riveting world of WordPress development for the greener pastures of helping a government startup manage its website, and while I’ve become pretty taken with Jekyll lately, there will always be a part of me that loves WordPress. And so, like a good hacker, I started a side project I’m calling rePress (a name that, admittedly, needs work—see below).

There have been a few different ways people have approached the task of marrying WordPress with static site generators. Ben Balter’s WordPress to Jekyll exporter is one that takes on Jekyll specifically, then there’s StaticPress, a plugin for WordPress that transforms your installation into a static site, and finally CFPB is taking on the task of building a static site generator that will pull from WordPress and other APIs. rePress takes a different tack but is inspired by these other initatives.

The first two of these solutions are WordPress plugins, and the second generates content from an API. This combines the two ideas by creating generator plugin for Jekyll sites that relies on the REST API currently being integrated into WordPress Core. Right now that API is only available as a plugin, but it will one day (soon, I think) require only a clean WordPress installation.

Once you have the API exposed, you need only point Jekyll to the root endpoint and run jekyll build on your server or your local environment. Right now it will grab the 9 most recent posts and parse out the published title, date, tags, authors, and excerpts, and, of course, the post content and generate HTML files with proper Jekyll frontmatter. This has a couple benefits: it allows you to import your WordPress posts without exporting any files and it allows you to choose whether to write Jekyll Markdown or use the WordPress editing interface.

It definitely has a long way to go, but it’s something I’ve been excited about creating pretty much since the REST API project was first announced. I’ll be pushing updates to GitHub, and would love any suggestions you have. In particular, I kind of hate the name I came up with, but all the original ideas like JekyllPress, StaticPress, and Hyde all mean other things related to Jekyll and WordPress. So here I am, with a name that means subdue by force which is not at all what this does or is intended to do. I’m open to name suggestions but know that it’ll probably change at some point.

Discuss on HackerNews.

How can I Configure WordPress to Handle Dynamic Hostnames?

An increasingly common problem enterprise-level WordPress installations will face is how they handle build, staging, and production environments where IP addresses inside a VPN use a different hostname to access the same server as those outside the VPN. In this case, the wp-config.php file is a little more complicated than in the famous 5-minute install.

It’s somewhat common practice now to lock WordPress’s site URL setting in code rather than in the settings menu. Mostly people do this because it is good insurance that nobody will ever change them but at my client we do it so that local environments, and our private and public servers can all share the same wp-config. We did it, fairly standardly, with the HTTP_HOST key from the $_SERVER superglobal. It’s pretty neat and makes life really easy.

We ran into a problem with our unified wp-config this week when a new load-balancing and proxying environment caused ‘HTTP_HOST’ to point at an inaccessible address in some environments. What to do?

The proxy was ferrying our visitors around using a standard called X-Forwarded-For (XFF). If the user was coming from outside the VPN, their request would be forwarded through to the correct location. Simple enough but, because the requests are all pointing to an internal hostname, HTTP_HOST was resolving to an address inaccessible to the user and thus all our static assets were unable to load. The problem turned out to be easy to solve.

As it turns out an X-Forwarded-For is often accompanied by an X-Forwarded-Host (the hostname the user was trying to reach). We simply sniff out whether $_SERVER has a X-Forwarded-Host key and set site_url and wp_home to the X-Forwarded-Host and fall back on HTTP_HOST for non-forwarded environments. Something like this:

if ( array_key_exists( "HTTP_X_FORWARDED_FOR", $_SERVER ) ) {
    define( "site_url", $_SERVER["HTTP_X_FORWARDED_FOR"] );
    define( "wp_home", $_SERVER["HTTP_X_FORWARDED_FOR"] );
} else {
    define( "site_url", $_SERVER["HTTP_HOST"] );
    define( "wp_home", $_SERVER["HTTP_HOST"] );
}

Writing Integration tests in WordPress

Integration testing, like unit testing, is a best practice with the goal of evaluating a piece of software’s ability to interface with the rest of a system. Earlier I elaborated on the distinction between integration and unit testing and I won’t repeat myself here. Instead I’ll briefly expand our definition of integration test and demonstrate how to use the WordPress Unit Test Suite to test a plugin.

What’s an Integration Test?

Tests which execute your code directly to determine if it properly interfaces with its dependencies are called integration tests. They require the greater system be installed in order to verify where a failure might occur. Unlike unit tests, integration tests do not necessarily test the correctness of your code as much as they do the system’s stability and your code’s interaction with it. For example, if we’re building a method to save data passed through a POST request into a database, a unit test would demonstrate that our method prepares that data appropriately and calls the correct methods for saving the data. An integration test would actually instantiate the database and save the record. For this reason, integration tests are more expensive. You’ll recall that the WordPress Unit Test Suite (WUTS) requires a dedicated MySQL database and a working copy of WordPress in order to execute tests. Reading and writing from MySQL can be an intensive process.

For a plugin we are developing at my client, we had five tests that verified a feature. With WPUTS, the tests took nearly 42MB of memory out of our server, when we tested the same feature with unit tests, we shaved it down to 8, about a 5.25x improvement. The unit tests might be faster, but the data gleaned from an integration test is valuable in its own right. How else do you evaluate why a plugin fails when all of its unit tests pass? Perhaps it’s because you are sending the wrong data to the methods you’re mocking. Integration tests will catch that, unit tests won’t.

How to do it

First install WP-CLI as it will make everything much easier. The directions on getting the plugin tests initialized through WP-CLI are very clear and I won’t repeat them here. This will install a separate copy of WordPress and a separate database for testing. If you run phpunit from your root directory, you should output similar to this travis build. Passing tests validate the stability of WordPress, the failing and skipped tests are either incomplete or anticipate features in development. The tests will probably take under two minutes to execute depending on your system. If you cd into wp-content/plugins/your-plugin you should see a tests directory, a phpunit.xml file, and a bootstrap.php inside the tests directory. Run phpunit from your plugin’s root directory and it will execute any files which begin with ‘test-‘ and end with ‘.php’. Go ahead and create a test-your-plugin.php file inside the tests directory.

ProTip:To change which files phpunit will pick up when you run it, modify the bootstrap.php file.

Your first test

As we did with unit testing, let’s start with a simple test we know will always pass. You’re going to want to first extend the WordPress unit test suite:

class YourPluginTests extends WP_UnitTestCase {

}

Then inside that class, write a simple test:

function testIsAlwaysTrue() {
    // Arrange
    $foo = true;

    //Assert
    $this->;assertTrue($foo);
}

`$foo` will always be true and that test should pass if you run phpunit. Now let’s take a look at some of the features the WPUTS has to offer.

The factory

WPUTS has a factory for creating things you might need for your tests. Let’s say we’re writing a method to check the title of a post. Since we have none, WPUTS should create one for us. Let’s write a test that checks if a newly created post has a title.

function testPostHasTitle() {
    // Arrange
    $post_id = $this->factory->post->create();

    // Act
    $post = get_post($post_id);

    // Assert
    $this->assertTrue(!empty($post->title));
}

That’s a fine looking test, and it passes! But what does it tell you? Does it verify the `get_post()` method? In some ways it does, but it certainly doesn’t verify all of `get_post()`. In this case it mostly verifies that a post can be fetched out of the database. Let’s take the same method [we verified earlier][4] and write an integration test for it, only this time we won’t mock it. We’ll start with the same name:

public function testTestPostExpectsMetaDataSaved(){

}

In our arrange section we’ll use the factory to create a post, and we won’t do any mocking. Remember, we’re interested in whether the system is functioning with our code in it. Our arrangement, in this case, will also include a variable `$expected` we will use in the assert section. The act section will be mostly the same, and the assert section will contain a check to `get_post_meta` and an `assertEquals` statement compairing $expected and our result. If all is well with our `save_meta_data` and the WordPress methods used in it, they should be the same. We can also write a message to print if the test fails.

// arrange
    $post_id = $this->factory->post->create();
    $expected = 'New meta value'

    // Act
    $methods = new MetaMethods();
    $methods->save_meta_data($post_id);

    // Assert
    $actual = get_post_meta($post_id);
    $this->assertEquals(
      $expected,
      $actual,
      'Meta data expected to equal ' . $expected . ' but instead was ' . $actual);

If we run the test now, it will either fail or error out because we haven’t written $methods->save_meta_data yet. Our development goal: make the test pass. Once this test passes, we can say, with a bit more certainty, that our method saves meta data properly.

Unit and integration testing are similar but one distinct advantage of integration testing is that we can use the testing environment to experiment with core WordPress functions. We can use it to get under the hood, as it were, without digging through the codex and StackOverflow. If your unit tests are passing but your plugin isn’t working, try running an integration test and see if maybe you’re not feeding the mocked function the proper data.

Testing of any kind allows you to think carefully about what your method should do and how to make it happen. Do you need a full post object, or do you need only the ID? Do you need all those conditionals? How much work is this method actually doing? The more you test, the simpler your code will be. Simpler code is easier to test, troubleshoot, and extend. It is important, however, to be mindful of the differences between the two concepts as they have implications for what you can and can’t say for certain about your code.

As before, our full test is below:

class YourPluginTests extends WP_UnitTestCase {
    function testPostHasTitle() {
        // Arrange
        $post_id = $this->factory->post->create();

        // Act
        $post = get_post($post_id);

        // Assert
        $this->assertTrue(!empty($post->title));
    }

    public function testTestPostExpectsMetaDataSaved(){
        // arrange
        $post_id = $this->factory->post->create();
        $expected = 'New meta value'

        // Act
        $methods = new MetaMethods();
        $methods->save_meta_data($post_id);

        // Assert
        $actual = get_post_meta($post_id);
        $this->assertEquals(
          $expected,
          $actual,
          'Meta data expected to equal ' . $expected . ' but instead was ' . $actual);
    }
}

Using Composer to Manage a WordPress Installation

The team at Roots.io have a fantastic walkthrough of Composer and why and how you should use it in managing a WordPress site. Composer is a wonderful piece of technology that reduces the headache of figuring out how to managing the individual components of your site to a single file and software solution. With WordPress, a utility like composer breaks an installation into discrete pieces. This allows you to automate deployments and updates of your site using only the composer.json file and isolating each part of your site to its own maintainable place. I plan to make composer-automated installations the default on all future WordPress projects I undertake.

Octopress: Six Months Later

When I was a week into this blog, I wrote down some of the reasons I liked Octopress, my initial impressions of it as a blogging platform and whether it could compete or replace WordPress. It was a leap for me, a WordPress developer and long time fan of the platform. In general I have found Octopress to be an interesting experiment in hacker blogging but am back to WordPress as of this entry.<!–more–>

Starting, as before, with what I (still) like about Octopress. There is still a lot to like.

  1. I love writing in Markdown. WordPress.com recently added Markdown support, so it’s only a matter of time before I can write in Markdown here without a plugin, but being able to practice What You See is What You Mean (WYSIWYM) while blogging without writing straight HTML is really quite convenient. When I write on WordPress blogs at work I often forget it’s either straight HTML (too cumbersome) or the TinyMCE What You See Is What You Get (WYSIWYG) editor (too unreliable).
  2. Simple local previews are another thing I really love. rake preview is up there with Django’s ./manage.py runserver test server in simplicity. What I would change is that the rake server is not nearly as competent as Django’s when it comes to compiling sites after making changes and letting you know about errors. For example, using quotation marks in categories causes errors in site generation with Octopress but the only output in the preview terminal is the somewhat unhelpful WARN Could not determine content-length of response body. Set content-length of the response or set Response#chunked = true. Nevertheless it is quite simple to get a full, local, site preview while you’re still editing.
  3. Accidental publishing happens less frequently. This relates to 2 in that you have to be pretty deliberate about publishing the post for the world to see. Saving the file locally preserves your work. rake preview let’s you see it in a browser (almost) exactly as it should appear. Getting it out in the public, however requires rake gen_deploy run from the terminal.

With all that said, Octopress has a long way to go. Most of what I missed is WordPress’s user interface and content management features.

  1. Drafting posts. In WordPress, your post isn’t given a published date until you hit Publish, at which point it records the exact moment in time you hit publish as the date posted. In Octopress, this timestamp is added as soon as you execute rake new_post[]. I’m a drafter. Sometimes I’ll start three blog posts at once to get some ideas on the page and then put them aside until I have time work on them. (I started this one on January 1 and look at me now.) December 23, for example, I wrote Why Unit Testing Matters in one go. But I also started two follow on posts about writing good unit and integration tests. I ran rake new_post three times and each post had the same publish date even though the last two hadn’t been published yet! When I rake deployed, I had the post I wanted buried under two empty posts. When I finally finished the first of the others it was 2014 and I had to manually change the date and time as well as the published status. Manually managing these publish times was a bit of a nightmare.
  2. Visualizing published work. A blogging UI that can list posts and organize them by date and time published or category is incredibly useful when trying to reference older works. As is being able to quickly copy the permalink out of the admin (or right within the post editing UI in WordPress) and paste it into a link block. Octopress has no such mechanism and URLs can get really long. In fact, the permalink structure I’m using here is consistent with Octopress to maintain backward compatibility and I’m more or less stuck with it even though I’d rather it be much shorter.
  3. Version control over posts. This doesn’t matter to me as much anymore as it did in August. Markdown doesn’t version control very well anyway since lines are sometimes thousands of lines long. Also, with WordPress’s new drafting system, keeping track of changes in the post content is trivial and much more visual that it ever has been.
  4. Getting out. WordPress’s export/import functionality made switching to Octopress and it would have made switching back easy except that Octo has no similar feature. The upshot is that everything in Octo is straight HTML so importing wasn’t terribly difficult, but, manually re-entering the posts was time consuming and I’d rather not repeat it.

Paul Graham tweeted recently that static sites are “the fixies of the Internet”. I found that a compelling metaphor. To extrapolate it to my favorite bike company, WordPress is a complete Long Haul Trucker. Well built, tough and reliable enough to last you a long time. Octopress is the Cross-Check frame. It looks like it can do a lot but it’s unclear whether it’s a fixie, for touring, commuting, or something else entirely. The DIY aspects have a lot of advantages but also puts a lot of pressure on the user to decide what to do with it. Octopress clearly has a lot of advantages. But at the end of the day all I really want is to sit down and write a blog.

How can I use PHP Namespaces in WordPress Plugins

PHP has long had a problem of naming collisions. Because older versions of PHP had no way of declaring methods outside the global space, developers came up with several different ways of preventing and checking for namespace collisions, none of which treated the underlying condition. These many and varied solutions begged for a unifying standard as they made things like autoloading and package management increasingly difficult. PHP 5.3 introduced a feature called ‘namespacing’ to solve this problem and WordPress developers should begin adopting. With proper namespacing, WordPress plugin and themes will become clearer, more stable, and more portable.
<!–more–>

Prior to PHP 5, if you tried to name a method or class foo it might conflict with another similarly nammed method elsewhere in the system. Developers came to terms with this by ‘namespacing’ methods with a prefix. With this standard, foo became my_foo or gb_foo where the my_ or gb_ corresponded to vendor prefixes (gb, being my initials). It also led to wrapping every method in a conditional to check for namespace collisions:

if ( !function_exists(gb_foo) ) {
    function gb_foo( $bar ) {
        echo $bar;
    }
}

gb_foo('bar');

Look familiar? The problem with this should be easy to see. If that conditional returns false, my method `gb_foo` will never be fired and any time it’s called, that other `gb_foo` method will. Imagine if `gb_foo` was something like this:

function gb_foo($bar) {
    mysql_query('DROP TABLES *');
}

I think we can all agree that would be bad.

Namespacing is a concept familiar to many other programming languages that isolates your application from others in a standardized way. The global space should be reserved for only those things that should be available at all times. There is typically a character or pair of characters which globally signifies a namespace separator. In PHP it’s the backslash .

If properly namespaced, you can name your method foo() without any possibility of your method conflicting with anything else (unless you declare it twice in the namespace).

Namespacing also alleviates your need to wrap your methods in that conditional. A properly namespaced foo() method would look like this:

namespace gb;

function foo($bar) {
    echo $bar;
}

Let’s take a look at what’s going on here. On the first line we declare the namespace we want to use, in this case my initials gb. We can then declare classes and methods without worrying about stepping on any other methods. This is sort of like putting things in classes, but it’s even more safe. To call that ‘foo’ method, just type gbfoo('baz'); which should output ‘baz’. You can also declare classes inside the namespace just like you would normally, the difference is that when these are called, the namespace must be too. There are a few different ways of approaching this:

Consider the application lives in a file called test.php and all our files are in the same directory.

// test.php
namespace gb;
class Bar {
    public static function foo($bar) {
        echo $bar;
    }
}

Example one: ‘Use’ the namespace, declared at the top of the second file.

require_once(DIR . '/test.php'); use gbBar;

Bar::foo('baz');

Example two: Call the method with the namespace and class prefixed.

require_once(DIR . '/test.php');</p>

gbBar::foo('baz');</p>

Example three: Instantiate the class as an object and declare the method from the object.

require_once(DIR . '/test.php');</p>

$object = new gbBar();

$object->foo('baz');

They’re all very similar and should look familiar. Again, all the namespace does is add a layer of abstraction away from the global space in order to prevent collisions. Where it becomes particularly useful is in autoloading with tools like composer. With namespaces autoloaded, developers do not even need to require the files where those classes exist. They only need to know the namespaces. Example one, then, becomes:

use gbBar;
Bar::foo('baz');

Pro tip: you can ‘use’ a namespace under another name. So if you have two classes Bar, you can redeclare them like this:

use namespaceBar as Bar;
use gbBar as Baz;

Baz::foo('bar');

You can also stack namespaces to isolate your individual plugins from each other: namespace gbmyAwesomePlugin; and namespace gbanotherAwesomePlugin serve as different namespaces for different plugins. It also keeps me safe from other ‘gb’s out there crowding my namespace.

Namespaces can also indicate where to find your application. With a fully namespaced plugin, you could even configure your WordPress install to use your plugin without ‘installing’ it. If you have composer doing that for you, you can autoload the plugin preconfigured the way you want it. WordPress is becoming an increasingly vibrant application development platform and namespacing will be key to it living in harmony with other PHP applications in complex systems.