function my_first_callback( $post_id, $post ) {
  // do something...
}
add_action('save_post', 'my_first_callback', 10, 2);

So far, pretty simple. Now let’s put something in our callback function.

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
}
add_action('save_post', 'my_first_callback', 10, 2);

Not a horribly complicated function. We’ll leave aside my reasons for creating a post in this callback (there’s a myriad of reasons why one might want to create or update a different post when a given post is saved) and focus on the consequences.

wp_insert_post(), called from my_first_callback() will once again trigger the save_post action, while we’re still in the middle of processing the first save_post action. So long as you avoid an infinite loop, there’s nothing necessarily wrong with that. But look closely inside do_action(), and you’ll find something else to worry about.

The $wp_filter array

WordPress stores all of your action (and filter) callbacks in the global $wp_filter array. This is a multidimensional array, with the hook names at the top level, the priority as the second level, and the callback at the third level. E.g., adding our callback above with add_action() is basically the same as:

$wp_filter['save_post'][10]['my_first_callback'] = array('function' => 'my_first_callback', 'accepted_args' => 2);

Inside do_action()

do_action('save_post') takes the $wp_filter['save_post'] array, sorts the priorities, then loops through each priority’s array of callback functions. Basically, a foreach loop nested inside of a foreach loop.

But the outer loop is not a PHP foreach loop. Instead, we manually progress through each priority using next(). Here’s the exact code in do_action():

do {
  foreach ( (array) current($wp_filter[$tag]) as $the_ )
    if ( !is_null($the_['function']) )
      call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
} while ( next($wp_filter[$tag]) !== false );

In many situations, this is functionally identical to a foreach loop, but in certain cases, it’s not.

Case 1: Adding callbacks while already looping through the hook

Let’s say that during your save_post callback function, you decide that you need to add another callback function with a later priority.

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'pistachio' ) {
    add_action('save_post', 'my_second_callback', 15, 2);
  }
}
function my_second_callback( $post_id, $post ) {
  // do something else
}
add_action('save_post', 'my_first_callback', 10, 2);

Due to the way do_action() is implemented, you can do this. my_second_callback() will be called at an appropriate(-ish) time (I’ll leave it as an exercise for the reader to figure out why it may not be in the exact order you might expect), because, by using next() instead of foreach, WordPress avoids making a copy of the $wp_filter['save_post'] array.

Case 2: Nested callbacks

Now lets go back to our original callback function, and give it a friend:

function my_first_callback( $post_id, $post ) {
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
}
function my_second_callback( $post_id, $post ) {
  // do something else
}
add_action('save_post', 'my_first_callback', 10, 2);
add_action('save_post', 'my_second_callback', 15, 2);

my_second_callback() will never be called if $post->post_type == 'post'. In fact, any callback with a later priority will not be called. How did that happen?

When my_first_callback() calls wp_insert_post(), we have, as mentioned above, some nesting going on with the save_post action. The inner call to do_action('save_post') cycles through the $wp_filter['save_post'] array until next() moves the pointer to the end of the array. After that loop is done, the outer call to do_action('save_post') doesn’t get its array pointer put back in the appropriate location. As far as it can tell, it’s looped through the entirety of the array and reached the end.

If do_action() used a foreach loop instead of the do-while construct with next(), it would make a copy of the $wp_filter['save_post'] array with its own pointer, and we wouldn’t have this problem, but then case 1 wouldn’t work. It looks like a conscious design decision, and I’m inclined to say the correct decision.

Making things right

So what do we do about that? Well, we can just avoid calling wp_insert_post() or wp_save_post() in our callbacks for the save_post hook. If you can avoid it, I highly recommend it. Sometimes, though, that’s not practical, so you have to take a different approach: put the pointer back.

If you know your callback will (or might) cause nesting of an action/filter, you need to figure out where the array pointer should be when you’re done, and put it there.

function my_first_callback( $post_id, $post ) {
  // track the current position of the array_pointer
  global $wp_filter;
  $wp_filter_index = key($wp_filter['save_post']);
  if ( $post->post_type == 'post' ) {
    wp_insert_post(array(
      'post_title' => 'A Post',
      'post_status' => 'publish',
      'post_type' => 'a_custom_post_type',
    ));
  }
  // put the pointer back
  reset($wp_filter['save_post']);
  foreach ( array_keys($wp_filter['save_post']) as $key ) {
    if ( $key == $wp_filter_index ) {
      break;
    }
    next($wp_filter['save_post']);
  }
}

At the moment, I’m happy to admit that this is not 100% robust. E.g., the array may have changed or been resorted since your function started. So you’re not guaranteed to return to the exact state you were in before your function was called. But you’re probably close enough, and much better off than if you hadn’t tried at all.

Creating the Page

First off, rather than the admin_menu hook, you’ll use the network_admin_menu hook to register your page. E.g.:

add_action('network_admin_menu', array($this, 'register_network_admin_pages'), 10, 0);

In your callback function, you don’t have the luxury of shortcut functions (e.g., add_options_page()) for registering your settings page, so you have to use add_submenu_page(), with 'settings.php' as your first argument. Alternatively, you can still use add_menu_page() to create a new menu section, just as you would with the single blog admin menu.

The WordPress settings API doesn’t entirely work on network admin pages, but you can still take advantage of the add_settings_section(), add_settings_field(), and do_settings_sections() functions to register and display your settings, if appropriate. But register_setting() is useless here.

The action attribute for your settings form should point to edit.php?action=Your_Unique_Action, for reasons we’ll soon discover.

Individual settings should be pulled from the network-wide site options table, using get_site_option().

Saving the Settings

Your settings form gets submitted to edit.php. To save your settings, you need to hook into the network_admin_edit_ACTION hook.

add_action('network_admin_edit_Your_Unique_Action, array($this, 'save_network_settings_page'), 10, 0);

Again, register_setting() doesn’t work on admin pages, so you’ll need to sanitize, validate, and save all your options yourself. Save the settings to the network-wide site options table using update_site_option().

After all your settings are saved, do a redirect back to your settings page. If you don’t WordPress will automatically redirect to the network dashboard.

wp_redirect(add_query_arg(array('page' => 'Your_Page_Slug', 'updated' => 'true'), network_admin_url('settings.php')));
exit();

What is a URL?

In WordPress, a URL indicates which posts to display. Your request is mapped to query variables (if you don’t have permalinks turned on, you’ll see these variables directly in your query string), and those variables are used to manipulate the database query in $wp_query->query(). It’s a very nice, consistent system: a URL equals one or more posts (or a 404 error). (NB. the admin section is a different beast entirely.)

With Drupal, a URL is an entry in the menu system. When Drupal sees the URL, it looks up the corresponding entry, and calls the function specified in that entry. That function is responsible for creating the contents of the page, be it a list of nodes, a form, flying monkeys, or what have you. You can use a module like Views to achieve results similar to WordPress, but you have a lot more power and flexibility to do something different with a given page.

Sometimes you want that power and flexibility in WordPress. You just want to say, “When a user visits this URL, call this function and display its output.” That’s not really the “WordPress way” of doing things, and it requires a fair amount of code to accomplish what seems to be a simple instruction.

Abstract the Details Away

So I went and wrote another WordPress plugin. WP Router abstracts away all the messy details of declaring a callback function for a URL in WordPress. One method call is all it takes to set up your path, your rewrite rules, your query variables, your access rules, your title, your template overrides. It reduces a few dozen action/filter callbacks to a small list of easy-to-understand arguments.

If you’ve every worked with Drupal’s menu system, you’ll find many of the arguments familiar, adapted, of course, for the WordPress framework. Read all about them in the usage notes, and check out the sample code included in the plugin.

Ongoing Development

Right now, this is at version 0.2, which is synonymous with “has all the features I thought to add initially, plus one more”. But I’m just one developer. What would make this plugin more useful to you? What doesn’t work like you expect it to? What part of the API is confusing? Please leave a comment here or create an issue in Github.

And if you’re interested in contributing, feel free to fork the project and send me updates. It’s hosted at Github, with released copied over to WordPress’s plugin repository. As usual with code I write, it’s licensed under the MIT License (i.e., do whatever you want with it, just mention where it came from).

Internet, meet Tirzah; Tirzah, meet Internet. I’m sure you’ll get along nicely.

$my_plugin = new My_Plugin();

in your main plugin file, and declare all your actions/filters in your class’s __construct() function, using something like:

add_filter('init', array($this, 'my_init_function'));

And then you go on to add your plugin’s JavaScript and CSS, register post types and taxonomies, look for query variables, etc.

I’m declaring that to be “wrong”, and I’m not going to do it anymore. Why? Because it’s not good objects-oriented design, and it seems to me that if you’re going to use objects, you should follow good object-oriented design patterns.

What problems come from the current practice?

1. Lack of coherency. The class is basically being used as a plugin namespace. It’s laudable to try to avoid polluting the global namespace with all your function names, but using a consistent, unique prefix for your functions accomplishes the same thing. Instead you end up with data and methods that look like they’re related to each other, but really have the most tenuous connection of being part of the same plugin.
2. Poorly implemented singletons. Every plugin class really needs to be a singleton. Having two instance of the class would cause a range or problems, from inefficiency (e.g., running the same query multiple times) to possible conflicts as the first instance of the plugin filters some data that is then re-filtered by the second instance. I’m not saying that singletons are inherently bad, but they are definitely overused (Wikipedia says so!, and, to quote the “Bible”, “Be suspicious of classes of which there is only one instance”), and when they are used, they should be used deliberately and with proper care taken to avoid multiple instances.
3. Barriers to code reuse and abstraction. Classes created this way can’t really be sub-classed (although I’ve yet to see a final keyword in front of a class), partially because of the singleton problem mentioned above, partially because there’s no clear definition of what the class is, so it doesn’t make sense to make a more specific version of it. This gets in the way of creating abstractions to share common code among similar classes, and greatly increases the complexity of any plugin of reasonable size.

What do we do about it?

I’ll be the first to admit that I don’t know all the answers. I’m playing with some solutions right now that seem to be working well, and I welcome any suggestions for improving on these ideas.

1. Distinguish between class members and instance members. PHP includes the static keyword, to let you declare a property or method to be a member of the class itself, rather then an instance of the class. This is the proper place for your configuration settings, registering post types, etc. Instead of instantiating the class to tell WordPress about this information, create a static init() function to call in your base plugin file. E.g., My_Class::init().
2. Use different classes for different things. Does your plugin create two separate post types? Create a class to declare each of them. Throw in some instance methods for interacting with your custom post meta.

Example

class My_Custom_Post_Type {
  const POST_TYPE_NAME = 'my_post_type';
  const IMPORTANT_META = 'my_important_meta';
  private $post_id;
 
  public static function init() {
    add_action('init', array(get_class(), 'register_post_type'));
  }
  public static function register_post_type() {
    $my_post_type_args = array(
      // some args go here
    );
    register_post_type(self::POST_TYPE_NAME, $my_post_type_args);
  }
  public function __construct( $post_id ) {
    $this->post_id = $post_id;
  }
  public function get_important_meta_field() {
    return get_post_meta($this->post_id, self::IMPORTANT_META, TRUE);
  }
}

This lets you abstract away the implementation (e.g., is it a custom post type or a custom table?) and just work with your new object’s well-defined interface. You can start doing things like creating sub-classes, using polymorphism, setting up factory objects to give you different types of objects depending on taxonomy terms, and all sorts of other concepts based on object-oriented design patterns. Basically, it lets us grow up and use the amazing advances in computer science and the discipline of coding that we’ve seen over the last several decades.

I would love to get some feedback on this. It’s a nascent idea that could use some better minds to help form it.

That would be the Cr-48 ChromeOS laptop that arrived unannounced at my door this week.

Haven’t had much chance to delve into it, yet, but at the moment it’s looking like a good computer for:

• The kitchen
• Children
• Business meetings
• Casual web browsing
• General on-the-go connectivity, when a smartphone just isn’t enough (it does SSH and has a full-size keyboard)

More to come…

Rewrite Tags

In my previous post, I had a slug like project/%issue_project%/issue for my issue post type. What exactly is that %issue_project% in the middle of that?

That would be a rewrite tag. WordPress uses these as keys for regular expressions it will add to its rewrite rules. When you add a custom post type or a custom taxonomy, WordPress automatically creates appropriate rewrite tags for you. E.g., when you create an issue post type, WordPress will automatically create a rewrite tag called %issue%, with the pattern ([^/]+), or (.+?) if it’s a hierarchical post type, and this regexp will be rewritten to post_type=issue&name=$matches[1].

In my previous post, %issue_project% was the tag for the rewrite rule matching the issue_project taxonomy I had created using register_taxonomy.

Making Your Own Rewrite Tags

Knowing all this, you can create your own rewrite tags and use them in the slugs for your custom post types.

For my issue/bug tracking plugin, I decided that I should use another custom post type instead of taxonomy for projects. That means that WordPress won’t automatically create the %issue_project% rewrite tag. I don’t want to use the %project% rewrite tag that it creates for my project post type, as that will add inappropriate (and conflicting) rules to my rewrite rules.

The solution is to create my own %issue_project% rewrite tag.

global $wp_rewrite;
$wp_rewrite->add_rewrite_tag('%issue_project%', '(.+?/)?', 'issue_project=');

This matches (.+?/)? in a URL and puts the match into an ignored query var. Having created the rewrite tag, I can now use it in my post type’s slug.

register_post_type('issue', array(
  'label'=>'Issues',
  'hierarchical' => FALSE,
  'rewrite' => array(
    'slug' => '%issue_project%issue',
    'with_front' => FALSE,
  ),
));

This creates rewrite rules like

[(.+?/)?issue/([^/]+)(/[0-9]+)?/?$] => index.php?issue_project=$matches[1]&issue=$matches[2]&page=$matches[3]

Creating Links

Whenever you create your own rewrite tags, or use them in non-standard ways in post type slugs, you have to handle the rewrite tag in a post_type_link filter, replacing it with the appropriate string.

add_filter('post_type_link', 'my_post_type_link'), 1, 3);
function my_post_type_link( $post_link, $post = 0, $leavename = FALSE ) {
  if ( strpos('%issue_project%', $post_link) === 'FALSE' ) {
    return $post_link;
  }
  if ( is_object($post) ) {
    $post_id = $post->ID;
  } else {
    $post_id = $post;
    $post = get_post($post_id);
  }
  if ( !is_object($post) || $post->post_type != 'issue' ) {
    return $post_link;
  }
 
  $project_slug = '';
  $project_id = get_post_meta($post_id, '_issue_project', TRUE);
  if ( $project_id ) {
    $project_slug = get_page_uri($project_id);
  }
  if ( !$project_slug ) { // remove project prefix
    return str_replace('%issue_project%', '', $post_link);
  }
  // put project slug in place of %issue_project%
  return str_replace('%issue_project%', 'project/'.$project_slug.'/', $post_link);
}

jQuery.ajax({
  url: mySolrUrl,
  data: myQueryParameters,
  success: mySuccessCallback,
  dataType: 'jsonp',
  jsonp: 'json.wrf'
});

Of course, for this to work the Solr server you’re accessing needs to be publicly accessible, which probably isn’t ideal for security.

function my_init() {
  add_post_type_support('page', array('excerpt'));
}
add_action('init', 'my_init');

That’s all there is to it. Works with WordPress 3.0+.

Update 2010-10-01: Hey, look, I made it into a plugin.

Thanks to Nick Veenhof, mrkandy, and their many commenters, from whom this script is derived.

php_installed=`dpkg -l | grep php| awk '{print $2}' |tr "\n" " "`
 
# remove all php packge
sudo aptitude purge `dpkg -l | grep php| awk '{print $2}' |tr "\n" " "`
 
# use karmic for php pakage
# pin-params:  a (archive), c (components), v (version), o (origin) and l (label).
echo -e "Package: php5\nPin: release a=karmic\nPin-Priority: 991\n"  | sudo tee /etc/apt/preferences.d/php > /dev/null
apt-cache search php5-|grep php5-|awk '{print "Package:", $1,"\nPin: release a=karmic\nPin-Priority: 991\n"}'|sudo tee -a /etc/apt/preferences.d/php > /dev/null
apt-cache search -n libapache2-mod-php5 |awk '{print "Package:", $1,"\nPin: release a=karmic\nPin-Priority: 991\n"}'| sudo tee -a /etc/apt/preferences.d/php > /dev/null
echo -e "Package: php-pear\nPin: release a=karmic\nPin-Priority: 991\n"  | sudo tee -a /etc/apt/preferences.d/php > /dev/null
 
# add karmic to source list
egrep '(main restricted|universe|multiverse)' /etc/apt/sources.list|grep -v "#"| sed s/lucid/karmic/g | sudo tee /etc/apt/sources.list.d/karmic.list > /dev/null
 
# update package database (use apt-get if aptitude crash)
sudo apt-get update
 
# install php
sudo apt-get install $php_installed
 
sudo aptitude hold `dpkg -l | grep php5| awk '{print $2}' |tr "\n" " "`
 
#done

Of course, make sure to restart Apache when you’re finished.