Xdebug is not friends with WordPress + create_function()

If you use Xdebug for debugging WordPress-based sites there’s something you should be aware of. If function created with PHP’s create_function() are hooked to WordPress actions or filters, any time $wp_filters is in the scope Xdebug sends invalid XML to the Xdebug client, (like your IDE). If the Xdebug client doesn’t deal with the invalid characters before attempting to parse the XML it will fail. IDEs deal with the parsing failure in different ways, SublimeTextXdebug doesn’t show the call stack or list of current variables but doesn’t crash entirely so debugging can continue. I don’t know how other IDEs handle the failure.

Why the XML is Invalid

create_function() makes a new function, gives it a random name that starts with a null character, and returns that function name as a string. When that string is passed to WordPress’s add_filter() or add_action() functions the name that create_function() returned is used as an array key in deep within the $wp_filters global. When Xdebug sends the list of variables back to an Xdebug client it is sent as XML and the null character encoded as � which is illegal in XML.

How to solve the Problem

Ideally Xdebug would only send valid XML to the Xdebug client, but the bug report has been open for a year and doesn’t seem to be high priority so developers should solve the problem by avoiding create_function()

Avoiding create_function() is Good Coding

create_function() eval()‘s the code that’s passed as the second argument, and eval() is something to be avoided, so create_function() is too. This Xdebug bug makes us avoid create_function() for actions and filters in order to keep Xdebug useful, with the side effect of making our code a bit more secure.

Adding to a WordPress page’s URL without changing the URL of its Child Pages.

I was recently asked to add an extra path component to the URL of a WordPress page for SEO reasons. It took some diving into the internals of WordPress. Here’s the setup:

  • WordPress is installed in the site root, at example.com
  • We are using a static homepage
  • The company blog is at example.com/blog/
  • I was asked to make the blog URL be example.com/blog/some-extra-keywords/ without changing the URL of the current and future blog posts, which are currently example.com/blog/post-name/

There are 3 things required to make this work:

  1. A filter to tell WordPress to process requests for /blog/some-extra-keywords/ as if they are for /blog/
  2. A filter to change permalinks from /blog/ to /blog/some-extra-keywords/ (Optional, but recommended).
  3. A redirect from /blog/ to /blog/some-extra-keywords/ (Also optional, but also recommended).

Treat /blog/some-extra-keywords/ requests like /blog/

We don’t want to change the URL of the blog page in WordPress’s Edit Page screen because that will change the URL of past and future all blog posts. We need to tell WordPress that a request for /blog/some-extra-keywords/ is a request for /blog/. This is done by adding a filter to WordPress’s request filter hook:


/**
* Make the URL /blog/some-extra-keywords/ respond as /blog/
* would.
* @param array $request The request array that WP generates.
* @return array The modified request array.
*/
function jb_filter_blog_url_request( $request ) {

if ( isset( $request['name'] ) && 'some-extra-keywords' == $request['name'] ) {
// it's a page we're requesting. If you're doing this to something other
// than a page, try setting $request['name'], and don't unset it 2 lines
// later
$request['pagename'] = 'blog';
unset( $request['name'] );
}

return $request;
}
add_filter( 'request', 'jb_filter_blog_url_request' );

Since WordPress identifies pieces of content by the last part of the URL, (the “name”), that’s all we have to change. In this case, because the blog is on a page, we had to set $request['pagename'].

Note: This is optional, but recommended. If you don’t do this you must do the next item, (redirect /blog/ to /blog/some-extra-keywords/), but you get the most SEO benefit if you do both.

With #1 it’s time to change links to the blog page to point to the new URL. The old URL still works, and you’ll be redirecting it in Step 3, but modifying the links cuts out a round-trip to the server, making your site faster, and it means that anytime a spider crawls the site it will find the correct URL.

Again, we create a filter function and hook it up. Because I’m doing this all to a page, I’m hooking on to the page_link filter, but the function also works with the post_link filter. In fact, I originally used the post_link filter, which doesn’t work for pages, and spent a while banging my head against a wall trying to figure out why it didn’t work.

By hooking into page_link or post_link you’ll modify the URL everywhere it is generated with get_permalink(), which is almost everywhere. Menus, lists of pages, and even the XML Sitemap that Yoast’s WordPress SEO plugin makes will be have the new URL. If you have typed the URL somewhere this filter will not change it, but that’s why you’ll set up a redirect in Step 3.

The code:

/**
* Modifies the blog URL when it's requested using get_permalink().
*
* Note that this filter is set up to work on both posts & pages, and the
* post_link and page_link filters don't pass quite the same parameters:
* - $post is an post object for post_link and a post ID for page_link, so we
* get the post object if $post is numeric
* - $dontuse is completely different between the two filters, but not needed,
* so we ignore it.
*
* @param string $url The URL to be filtered.
* @param mixed $post The post ID or post object that corresponds to $url
* @param mixed $leavename Differs depending on filter. Ignore.
* @return string The possibly-modified URL.
*/
function jb_modify_blog_url( $url, $post, $leavename ) {
$true = false;

// don't do it in the admin, I'm afraid the modified URL will get
// added to the URL slug field on the Edit Page screen, and get
// permanently added, with another copy of it being added every time
// the page is saved.
if( ! is_admin() ) {

if ( is_numeric( $post ) ) {
$post = get_post( $post );
}

if( 'blog' == $post->post_name ) {
$url .= 'some-extra-keywords/';
}
}
return $url;
}
add_filter( 'page_link', 'jb_modify_blog_url', 10, 3 );

The magic is in the third if condition: If the page name is ‘blog’ add the extra keywords to the URL.

Redirect from /blog/ to /blog/some-extra-keywords/

Note: This is optional, as well, but if you don’t do it the blog homepage will be available at both /blog and /blog/some-extra-keywords/ which could lead to a duplicate content penalty from Google.

We’re going to do a 301 Redirect to tell search engines that the blog is now at /blog/some-extra-keywords/. I’m going to do this in a .htaccess file because that way the web server doesn’t have to start PHP or WordPress.

If you’ve already got a rewrite section in your .htaccess file, add the following line to it:

RewriteRule ^blog/?$ /blog/some-extra-keywords/ [R=301,L]

This will redirect both /blog/ and /blog, (the first ? makes the slash right before it optional), to /blog/some-extra-keywords/. If you don’t have a rewrite section, add one:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /

RewriteRule ^blog/?$ /blog/whole-house-fan-energy-saving-tips/ [R=301,L]

</IfModule>

And that’s it.

Improving Versioning of WordPress Static Files

I was recently asked to improve the PageSpeed and YSlow scores of a WordPress-based website that I work on. One of the items that PageSpeed checks is "Don't include a query string in the URL for static resources," (under the "Leverage Proxy Caching" heading). I suspect this is most important when you are using a CDN, or otherwise run through a proxy server. WordPress puts a version in the query string of any JavaScript or CSS that's enqueued using wp_enqueue_script() or wp_enqueue_style().

Interestingly, PageSpeed doesn't seem to complain about the WordPress-included static resources that have a query string on the URL, only about static resources on 3rd-party URLs. I'm not sure why this is, but let's remove the query strings from the WordPress-included static resources anyway, while still maintaining a version somewhere in the URL so we can set far-future Expires headers.

The format of a WordPress version tag is ver={version number}, like this: example.com/wp-content/themes/theme-name/style.css?ver=2.0.5.4, but example.com/ver2.0.5.4/wp-content/themes/theme-name/style.css should be more cacheable. There are two steps to making this happen:

1) Use Apache's mod_rewrite to Serve the Correct File to the Updated URL

In step 2 we'll be moving the version tag to the beginning of the URL, we only need one RewriteRule to make it work:


# This goes in your .htaccess file, before the WordPress section
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /

## Cache-Busting ##
RewriteRule ^ver([\d\.\-a-zA-Z]+)/(.*) $2?ver=$1 [L] #match something with the version tag right at the beginning of the URL
## Done cache-busting ##

</IfModule>

The rule above matches any URL that starts with "ver" followed by any number of letters, numbers, periods, dashes, and underscores, captures that collection of characters up to the first forward slash, then it captures everything after the first forward slash. The URL is rewritten as $2?ver=$1 where $2 is everything after the version tag, (the original URL, with no version tag), and $1 is the version number that's added, internally, to the query string, but never appears in the browser.

Note: It is probably possible to leave off the ?ver=$1, but I haven't tried it yet.

Now example.com/wp-content/themes/theme-name/style.css?ver=2.0.5.4 and example.com/ver2.0.5.4/wp-content/themes/theme-name/style.css should both serve up the same style.css file.

2) Filter the URLs for Enqueued Scripts & Styles to Move the Version Tag from the Querystring into the Path

The URL for every enqueued Javascript is filtered by the script_loader_src filter, and the URL for every enqueued stylesheet is filtered by the style_loader_src filter, so we'll use these filters to put the new, improved URL in the HTML. This is an absolute URL, so we can take it apart, move the parts around so that it looks how we like. Here's the function I'm using to change the URLs, plus two lines to hook on to the filters:


/**
* Changes WordPress's default versioned URLs from putting the verion in the
* querystring to putting the version as part of the file page, (requires
* .htaccess modification to work). If there's no version in the querystring
* one can be added by setting the $defaultversion.
* @param string $url The URL to change the location of the version.
* @param mixed $defaultversion A string default verion. Defaults to false, (
* no default version).
* @return string The new URL.
*/
function jb_better_versioned_url( $url, $defaultversion = false ) {

// don't bother for the admin
if ( ! is_admin() ) {

// parse the URL
$parts = parse_url( $url );

// and the querystring
$query = wp_parse_args( $parts['query'], array() );

// check if there's a version in the querystring. If so, do more.
if ( isset( $query['ver'] ) || false !== $defaultversion ) {

if ( isset( $query['ver'] ) ) {
// prepend "/ver" + {version value} to the *path*
$parts['path'] = '/ver' . $query['ver'] . $parts['path'];

// unset the version in the querystring, since it's in the path now.
unset( $query['ver'] );
} else {
$parts['path'] = '/ver' . $defaultversion . $parts['path'];
}

// if this is a PHP file just let it be.
if( ! preg_match( '~\.php$~', $parts['path'] ) ) {

// start rebuilding the URL string
$url = $parts['scheme'] . '://' . $parts['host'] . $parts['path'];

// see if there's still anything in the query
if ( count( $query ) > 0 ) {

// rebuild query with whatever remains
$parts['query'] = build_query( $query );

// append it to the URL string
$url .= '?' . $parts['query'];
}
}
}
}

return $url;

}

// hook onto the filters
add_filter( 'style_loader_src', 'jb_better_versioned_url' );
add_filter( 'script_loader_src', 'jb_better_versioned_url' );

With these two modifications all of your JavaScript & CSS will have the version in the path instead of the querystring. In addition, any images, fonts, or anything else referenced with relative URLs from your stylesheets will have the version in the beginning of their URL, which will be rewritten and the file served properly. This way if you ever have caching problems you can bump a version number and browsers will pull new versions of all your static resources.

A Word of Warning

This involves considerable coding acrobatics, and adds complexity to your WordPress-based site, for speed improvements that may not be very large, and may not exist at all, so use this method at your own risk.

I have this code in production, but would love to hear the opinions of others on it, that's what the comments are for, or Twitter, or elsewhere - just let me know where the technique is discussed.

Starting a Side Project

There’s a side project that I’ve had in my head literally for years. It will solve a minor annoyance I have that comes up a couple of times per year, and an extremely basic version should be quite quick to put together. Even though I’m snowed under with work, one of the annual events that the project will help with is coming up very quickly, so I’m going to get a rough version online to use, with my family, and see what works and what doesn’t. I also intend to blog about the process, and track the time spent on the project.

The nature of the project will be kept secret for a while.

Why now, After so many Years?

TL;DR: I think that web development has progressed to a point that I can get a lot of value out of the project for a reasonable amount of work.

For years this was “the project that I would learn Rails with,” back when Rails was the cool kid on the block. Now PHP, which I’ve worked with for years, has grown up and I don’t feel the same need to learn Rails. This is a chance to try some modern PHP techniques that are difficult to push into legacy projects, in an environment where I’m the one who will suffer if I screw up.

There’s a heavy mobile component, so I plan to use a Responsive design, which I haven’t gone all-in on before, and I recently learned a bunch of performance tricks, so stay tuned for some greased lightning.

SASS, and Grunt build routines for SASS, Grunt, and images have made their way into legacy projects but I’ve never started a project with these in place, and I’m excited to see how it goes.

Finally, by building on the old-fashioned LAMP stack I can host the project on existing servers at no additional cost so the only cost will be my time.

Source, Open and Closed

This unlike a couple of other projects, this one will be largely closed-source. I think it may be a viable business so I intend to find out before giving it away for free. This means I got to have adventures in setting up a Git server instead of relying on GitHub.

I will be sharing things that are not core to the business such as interesting techniques, and maybe my Gruntfile. If the project doesn’t become a business, I may release the source, only time will tell.

Conditionally Loading Javascript & CSS with Fancybox for WordPress

The Problem

I’ve been working on improving the performance of a client’s WordPress-based website recently and it’s become very clear to me just how much CSS & Javascript plugins load, even when it’s not needed.

On this particular website 47% of the Javascript and 57% of the CSS loaded on the site’s homepage is not required on the homepage, but is required elsewhere, so it should be loaded conditionally. Sometimes this is easy, but sometimes it’s not.

Fancybox for WordPress is not an easy plugin to make load client-side resources, after all, it’s made to show a lightbox on any image, and especially on any gallery. When the wp_enqueue_scripts action happens, where it is recommended that we set the scripts and styles that will be used on a page, we don’t yet know what will be on the page. Fortunately, we can call the wp_enqueue_script() function after that, during the body of the page, and those scripts will be printed in the wp_footer() function. The same is true for wp_enqueue_style(). So, here’s what we do:

  1. Stop Fancybox for WordPress from including its scripts & styles by default.
  2. If a gallery or image that we want to use Fancybox on is displayed, we tell WordPress to display the Fancybox scripts & styles in the footer.
  3. Enjoy faster pageloads.

Sounds simple, but there are a few interesting bits. Now for the code.

The Code

I use three functions to check if the Fancybox scripts & styles are needed. They can be in a theme’s functions.php, (where I have them at the moment), or they could even be rolled into their own plugin.

First tell Fancybox not to include its code by default. Instead of manually dequeuing every style & script, remove the Fancybox functions that do the enqueuing from the wp_enqueue_scripts and wp_head action hooks:

// don't enqueue Fancybox scripts by default.
function jb_dequeue_fancybox_css_js() {
remove_action( 'wp_enqueue_scripts', 'mfbfw_styles' );
remove_action( 'wp_enqueue_scripts', 'mfbfw_scripts' );
remove_action( 'wp_head', 'mfbfw_init' );
}
add_action( 'wp', 'jb_dequeue_fancybox_css_js' );

Next create a function that re-enables Fancybox, and remembers that it did so. Here there are two static variables, which will hold their value between function calls, (kind of like hidden globals), which store state. The $fancybox_is_used variable is returned so this function can be called with no arguments to find out if Fancybox has been used on page. Note the priority of 25 when hooking mfbfw_init() to the wp_footer action. This is needed because mfbfw_init() prints some Javascript to the page that relies on jQuery, and WordPress prints the enqueued scripts in the wp_footer action with a priority of 20, so mfbfw_init() needs to execute with a priority higher than 20.

function jb_fancybox_is_used( $used = false ) {

// this is returned so we can call this function with no arguments to learn
// if Fancybox has been used on a particular page.
static $fancybox_is_used = false;

// remember if Fancybox has been re-enabled already, so we don't enqueue the
// scripts multiple times
static $fancybox_is_setup = false;

if( $used === true ) {
$fancybox_is_used = true;
}

if( $fancybox_is_used && ! $fancybox_is_setup ) {
if( function_exists( 'mfbfw_styles' ) ) {
mfbfw_styles(); // enqueue fancybox styles
mfbfw_scripts(); // enqueue fancybox scripts
// the 25 is important. WordPress prints footer scripts in the
// wp_footer action with a priority of 20, and mfbfw_init() has to
// be
called after the footer scripts are already on the page.
add_action( 'wp_footer', 'mfbfw_init', 25 );
}
$fancybox_is_setup = true;
}

return $fancybox_is_used;
}

Finally, make a function that looks for places where Fancybox is used on the page. On the site I’m working on the CSS class fancybox is used on images and in galleries that I want to be Fancyboxed, so I look for the string “fancybox” in the_content filter, and when it’s found I call jb_fancybox_is_used( true ) to re-enable Fancybox on the page. I added this to the_content with priority 11 because shortcodes, including gallery shortcodes, are executed at priority 10, and I want to be able to look through the output of short codes for the fancybox CSS class:


function jb_hunt_for_fancybox( $content ) {

if( false !== stripos( $content, 'fancybox') || false !== stripos( $content, 'thickbox' ) ) {
jb_fancybox_is_used( true );
}
return $content;
}
add_filter( 'the_content', 'jb_hunt_for_fancybox', 11 );

If you include a something you want to fancybox in a template you can call jb_fancybox_is_used( true ) manually from the template file to include the CSS & Javascript.

Other Ways

This isn’t the only way to conditionally include Fancybox’s Javascript & CSS. Instead of using jb_hunt_for_fancybox() to filter the_content there’s probably an action or filter in the gallery shortcode that jb_fancybox_is_used() could be hooked onto. It may even be possible to use the $wp_query object in an action hook just before wp_enqueue_scripts to determine if there is content on the page that needs to be Fancyboxed, let that decide whether or not to run jb_dequeue_fancybox_css_js(), and forget about the other two functions.

Let’s Do Better

Plugin authors should be working hard to only add what is needed to each page load. Who is doing a great job? How can we hack our themes to bend other plugins to our will? Comment or tweet @johnbeales to let me know.