Suppose you have coded a complete online store for a client, with various products and categories. From a programmer's perspective, each URL of the site would be similar to http://example.com/shop.php?action=display&category=12&subcat=4. This URL easily maps to variables that can then typically fetch information from a database or perform actions.

The problem with that URL is that search engines may index it or just index http://example.com/shop.php, which may not even return something intelligible.

As a human user, you want a URL to be easy to understand and, if possible, memorable. For instance, consider the two URLs that would actually display the same product page:

The first URL is long and cryptic, whereas the second one is shorter and self-explanatory.

Even when URLs are not obscure like the first one, having a directory-like structure makes it much more understandable. The following two URLs would, for instance, point to the same page on a WordPress powered site:

The function that creates a new rewrite rule is add_rewrite_rule(), which needs two arguments, similar to how mod_rewrite works: a string defining the URL pattern to be matched and another string for the URL replacement. In your Rewrite Rules Shop plugin, write the following:

<?php
// Add rules
add_action( 'init', 'boj_rrs_add_rules' );
function boj_rrs_add_rules() {
    add_rewrite_rule( 'stores/?([^/]*)',
        'index.php?pagename=stores&store_id=$matches[1]', 'top' );
}
?>

This internally redirects all requests to the URL stores/something/ to the page Stores with an additional parameter, that is, index.php?pagename=stores&store_id=something.

Note that you passed a third parameter to add_rewrite_rule(), 'top', to specify that this list will be added before all rewrite rules, to make sure it is matched early and before built-in rules.

Now you need to add this additional parameter store_id to the list of registered query variables:

<?php
// Add the store_id var so that WP recognizes it
add_filter( 'query_vars', 'boj_rrs_add_query_var' );
function boj_rrs_add_query_var( $vars ) {
    $vars[] = 'store_id';
    return $vars;
}
?>

So far, you have modified the list of defined rewrite rules held in the $wp_rewrite object and the list of authorized query variables, kept in the $wp_query object. You're almost done!

The trick with rewrite rules is that when they are modified (if you add, modify, or delete one), you need to tell WordPress to refresh and rebuild the list. To do so, you can either visit the Permalink Options page in the admin area or use the function flush_rewrite_rules(). You can do this on plugin activation and plugin deactivation:

<?php

// Add the rewrite rule and flush on plugin activation
register_activation_hook( __FILE__, 'boj_rrs_activate' );
function boj_rrs_activate() {
    boj_rrs_add_rules();
    flush_rewrite_rules();
}

// Flush when deactivated
register_deactivation_hook( __FILE__, 'boj_rrs_deactivate' );
function boj_rrs_deactivate() {
    flush_rewrite_rules();
}
?>

Note the best practices when adding new rewrite rules:

You can now review the whole plugin.

<?php
/*
Plugin Name: List Stores
Plugin URI: http://example.com/
Description: A rewrite rule to list stores as children of the Stores page
Version: 1.0
Author: Ozh
Author URI: http://wrox.com
*/

// Add the rewrite rule and flush on plugin activation
register_activation_hook( __FILE__, 'boj_rrs_activate' );
function boj_rrs_activate() {
    boj_rrs_add_rules();
    flush_rewrite_rules();
}

// Flush when deactivated
register_deactivation_hook( __FILE__, 'boj_rrs_deactivate' );

function boj_rrs_deactivate() {
    flush_rewrite_rules();
}

// Add the rewrite rule
add_action( 'init', 'boj_rrs_add_rules' );
function boj_rrs_add_rules() {
    add_rewrite_rule( 'stores/?([^/]*)',
        'index.php?pagename=stores&store_id=$matches[1]', 'top' );
}

// Add the store_id var so that WP recognizes it
add_filter( 'query_vars', 'boj_rrs_add_query_var' );
function boj_rrs_add_query_var( $vars ) {
    $vars[] = 'store_id';
    return $vars;
}
?>

Code snippet boj_rewrite_shops/plugin.php

That's it for the plugin part: Now http://example.com/stores/denver/ redirects to the Stores WordPress parent page with the additional internal parameter store_id. You can now create that page and do a simple theme modification.

The additional internal parameter store_id is a query variable, which value can be read using the function get_query_var(), as following:

<?php
// Get store id
$store = get_query_var( 'store_id' );
?>

You can now create a regular WordPress page using the Add New Page admin page, but there is a twist: This page uses a page template.

When WordPress displays a Page (as opposed to a Post), it looks for the template file page.php within the current theme directory. You can set individual pages to use a more specific template file stores.php, simply by creating a new file within the theme directory and starting it as follows:

<?php
/*
Template Name: Store
*/
?>

Now in the Page write interface, within the Page Attribute meta box, you will be given the option to select this page template in the drop-down, as shown in Figure 14-1.

Figure 14.1. FIGURE 14-1

The page template code and layout depend on how your theme is coded, for instance how <div> elements are used and named. In this example you can assume the client's site is running WordPress' default theme, TwentyTen, so your store.php page template will have the same structure as the original page.php:

<?php
/*
Template Name: Store
*/
?>

<?php get_header(); ?>

<div id="container">
    <div id="content" role="main">

    </div><!-- #content -->
</div><!-- #container -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Within the <div id="content"> now resides the code that either lists all stores (if http://example.com/stores/ is requested) or displays a specific store information (when the requested page is for instance http://example.com/stores/miami/). To do so, you can simply do the following:

The complete page template store.php you can save into the theme directory follows:

<?php
/*
Template Name: Store
*/
?>

<?php get_header(); ?>

<div id="container">
    <div id="content" role="main">
    <?php

    // define all stores
    $stores = array(

'milwaukee' => array(
            'name'    => "Milwaukee Store",
            'manager' => 'Richie Cunningham',
            'address' => '565 N Clinton Drive, Milwaukee',
            'phone'   => '555-31337-1337'
        ),
        'springfield' => array(
            'name'    => "Springfield Store",
            'manager' => 'Bart Simpson',
            'address' => 'Evergreen Terrace, Springfield',
            'phone'   => '555-666-696969'
        ),
        'fairview' => array(
            'name'    => "Fairview Store",
            'manager' => 'Susan Mayer',
            'address' => '4353 Wisteria Lane, Fairview',
            'phone'   => '4-8-15-16-23-42'
        )
    );

    // Get store id
    $store = get_query_var( 'store_id' );

    // if store exists, display info
    if( array_key_exists( $store, $stores ) ) {

        extract( $stores[$store] );
        echo "<p>Store: $name</p>";
        echo "<p>Manager: $manager</p>";
        echo "<p>Location: $address</p>";
        echo "<p>Contact us: $phone</p>";

    // if store does not exist, list them all
    } else {

        // Get current page URL
        global $post;
        $page = untrailingslashit( get_permalink( $post->ID ) );

        echo '<p>Our stores:</p>';
        echo '<ul>';
        foreach( $stores as $store => $info ) {
            $name = $info['name'];
            echo "<li><a href='$page/$store/'>$name</a></li>\n";
        }
        echo '</ul>';
    }

    ?>
    </div><!-- #content -->
</div><!-- #container -->

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Code snippet boj_rewrite_shops/store.php

You can now create a regular page within WordPress, using this page template, as shown in Figure 14-2.

Figure 14.2. FIGURE 14-2

On the front side of the site, you can now access the main Stores page, located at http://example.com/stores/, which lists all stores and links to each individual store page, for instance http://example.com/stores/fairview/ as shown in Figure 14-3:

Figure 14.3. FIGURE 14-3

In the Permalink Options settings page, you can define custom permalinks using tags such as %year% or %monthnum%. You can now define a new tag %product% and use it in the permalink structure of the site:

<?php
// Create new tag %product% and handle /shop/%product% URLs
add_action('init', 'boj_products_rewrite');
function boj_products_rewrite() {
    add_rewrite_tag( '%product%', '([^/]+)' );
    add_permastruct( 'product', 'shop' . '/%product%' );
}
?>

The first function call, add_rewrite_tag(), defines the tag and what can match it. Here, the tag %product% matches one or more characters that are not a forward slash, using the regular expression ([∧/]+). This function call also registers a new query variable with the same name product.

The tag defined, the function add_permastruct(), describes a new permalink structure, with two parameters: an arbitrary name for the structure and how URLs and tags should be formed.

Now look at the rewrite rules that have been added to the $wp_rewrite object and its rules property:

[shop/([^/]+)/feed/(feed|rdf|rss|rss2|atom)/?$]
    => index.php?product=$matches[1]&feed=$matches[2]
[shop/([^/]+)/(feed|rdf|rss|rss2|atom)/?$]
    => index.php?product=$matches[1]&feed=$matches[2]
[shop/([^/]+)/page/?([0-9]{1,})/?$]
    => index.php?product=$matches[1]&paged=$matches[2]
[shop/([^/]+)/?$]
    => index.php?product=$matches[1]

Example URLs matching these rewrite rules could be the following:

These URLs can internally redirect to the following:

Congratulations: Using just two function calls, you created a complete, new permalink structure that can handle pagination and feed generation!

Now that requests to /shop/something/ successfully redirect to /index.php?product=something, you can integrate the existing product listing script. Here the actual script integration is commented and replaced with a simple output:

<?php
// If query var product as a value, include product listing
add_action( 'template_redirect', 'boj_products_display' );
function boj_products_display() {
    if ( $product = get_query_var( 'product' ) ) {
        // include( 'display_product.php' );
        echo "Here goes information for product <strong>$product</strong>";
        exit;
    }
}
?>

By hooking into the early action 'template_redirect', you can hijack the normal page display and, if the query variable product (registered by the previous add_rewrite_tag() function call) has a value, include the shop listing script. Don't forget to use exit() so that WordPress does not try to further handle the page display and, unable to find a post, output a 404 error.

To test for pagination or feed generation, you can also check the values of get_query_var('paged') and get_query_var( 'feed' ).

Flush the rewrite rules when they're created the first time, and your plugin is now complete and functional.

You can now review the whole plugin.

<?php
/*
Plugin Name: Products Permalink Structure
Plugin URI: http://example.com/
Description: Create a whole permalink structure
Version: 1.0
Author: Ozh

Author URI: http://wrox.com
*/

// Add permalink structure and flush on plugin activation
register_activation_hook( __FILE__, 'boj_products_activate' );
function boj_products_activate() {
    boj_products_rewrite();
    flush_rewrite_rules();
}

// Flush on plugin deactivation
register_deactivation_hook( __FILE__, 'boj_products_deactivate' );
function boj_products_deactivate() {
    flush_rewrite_rules();
}

// Create new tag %product% and handle /shop/%product% URLs
add_action('init', 'boj_products_rewrite');
function boj_products_rewrite() {
    add_rewrite_tag( '%product%', '([^/]+)' );
    add_permastruct( 'product', 'shop' . '/%product%' );
}

// If query var product as a value, include product listing
add_action( 'template_redirect', 'boj_products_display' );
function boj_products_display() {
    if ( $product = get_query_var( 'product' ) ) {
        // include( 'display_product.php' );
        echo "searching for product $product ?";
        exit;
    }
}

Code snippet boj_rewrite_products/plugin.php

To define the endpoint for your service, you can use the function add_rewrite_endpoint(), which needs two parameters: a string for the syntax of the endpoint (here format) and a number to identify on which "places," that is types of URLs, the endpoint will be added.

The file wp-includes/rewrite.php defines several constants to match "places" where endpoint will be added. For example with EP_CATEGORIES (which has a value of 512), you can match only URLs under the /category/ permalink, such as http://example.com/category/tshirts/format/qr/.

Following is a complete list of constants.

For instance, if you want to add an endpoint to author pages, you can write add_rewrite_endpoint('something', 2048) or add_rewrite_endpoint('something', EP_AUTHORS).

If you want to append an endpoint to both author pages and search pages, add the two place values: add_rewrite_endpoint('something', EP_AUTHORS + EP_SEARCH).

In your plugin add the endpoint to all URLs:

<?php
// Add the endpoint rewrite rules
add_filter( 'init', 'boj_ep_add_rules' );
function boj_ep_add_rules() {
 add_rewrite_endpoint( 'format', EP_ALL );
}
?>

This single function call registers /format/ as a valid endpoint to all URLs, and registers a new query variable, also named format. This enables URLs such as /tag/tshirt/format/qr/ to be internally rewritten to /index.php?tag=tshirt&format=qr.

You can now check the value of the query var format and modify the page output:

<?php
// Handle the custom format display if needed
add_filter( 'template_redirect', 'boj_ep_template_redirect' );
function boj_ep_template_redirect() {
 switch( get_query_var( 'format' ) ) {
 case 'qr':
 boj_ep_display_qr();
 exit;
 case 'json':
 if( is_singular() ) {
 boj_ep_display_json();
 exit;
 }
 }
}
?>

To finalize your plugin, you now need to add the following functions or features:

You can now review the whole plugin.

<?php
/*
Plugin Name: Format endpoint
Plugin URI: http://example.com/
Description: Add a /format/ endpoint to all URLs
Version: 1.0
Author: Ozh

Author URI: http://wrox.com
*/


// Add permalink structure and flush on plugin activation
register_activation_hook( __FILE__, 'boj_ep_activate' );
function boj_ep_activate() {
 boj_ep_add_rules();
 flush_rewrite_rules();
}

// Flush on plugin deactivation
register_deactivation_hook( __FILE__, 'boj_ep_deactivate' );
function boj_ep_deactivate(){
 flush_rewrite_rules();
}


// Add the endpoint rewrite rules
add_filter( 'init', 'boj_ep_add_rules' );
function boj_ep_add_rules() {
 add_rewrite_endpoint( 'format', EP_ALL );
}

// Handle the custom format display if needed
add_filter( 'template_redirect', 'boj_ep_template_redirect' );
function boj_ep_template_redirect() {
  switch( get_query_var( 'format' ) ) {
 case 'qr':
 boj_ep_display_qr();
 exit;
 case 'json':
 if( is_singular() ) {
 boj_ep_display_json();
 exit;
 }
 }
}

// Display JSON information about the post
function boj_ep_display_json() {
 global $post;
 // Tell the browser this is a JSON file
 header('Content-type: application/json');
 echo json_encode( $post );
 exit;
}

// Display a QR code
function boj_ep_display_qr() {
 // get current location and strip /format/qr/ from the URL
 $url = ( is_ssl() ? 'https://' : 'http://' )
 . $_SERVER['HTTP_HOST']
 . preg_replace( '!/format/qr/$!', '/', $_SERVER['REQUEST_URI'] );

// encode URL so it can be used for the QR code query
 $url = urlencode( $url );

 // Google QR code URL:
 $qr = "http://chart.apis.google.com/chart?chs=150x150&cht=qr&chl="
 . $url . "&chld=L|0";

 // Get the image generated by Google
 $image = wp_remote_retrieve_body( wp_remote_get( $qr ) );

 // Display QR code image
 header( 'Content-Type: image/png' );
 echo $image;
 exit;
}
?>

Code snippet boj_endpoints_format/plugin.php

The Rewrite API function you use to register a new feed is add_feed(), which needs two arguments: the feed name such as "atom" or, here, img, and the callback function that can output content.

<?php

// Register the feed
add_filter( 'init', 'boj_addfeed_add_feed' );
function boj_addfeed_add_feed() {
 add_feed( 'img', 'boj_addfeed_do_feed' );
}
?>

From now on, the URL http://example.com/feed/img/ will be handled by the callback function boj_addfeed_do_feed(). Because images in WordPress are actually the custom post type "attachment" as covered in Chapter 11, "Extending Posts," you can easily build your own $post and Loop to display the latest images in an XML ATOM manner. As usual flush the rules on activation and deactivation, and the plugin is complete.

You can now review the whole plugin.

<?php
/*
Plugin Name: Image feed
Plugin URI: http://example.com/
Description: Add a feed for latest uploaded images
Version: 1.0
Author: Ozh
Author URI: http://wrox.com
*/

// Add permalink structure and flush on plugin activation
register_activation_hook( __FILE__, 'boj_addfeed_activate' );
function boj_addfeed_activate() {
 boj_addfeed_add_feed();
 flush_rewrite_rules();
}

// Flush on plugin deactivation
register_deactivation_hook( __FILE__, 'boj_addfeed_deactivate' );
function boj_addfeed_deactivate() {
 flush_rewrite_rules();
}

// Register the feed
add_filter( 'init', 'boj_addfeed_add_feed' );
function boj_addfeed_add_feed() {
 add_feed( 'img', 'boj_addfeed_do_feed' );
}

// Callback function: echo the feed
function boj_addfeed_do_feed( $in ) {

 // Make custom query to get latest attachments
 query_posts(array( 'post_type' => 'attachment', 'post_status' => 'inherit' ));

 // Send content header and start ATOM output
 header('Content-Type: application/atom+xml');
 echo '<?xml version="1.0" encoding="'.get_option('blog_charset').'"?'.'>';
 ?>

<feed xmlns="http://www.w3.org/2005/Atom">
 <title type="text">Latest images on <?php bloginfo_rss('name'); ?></title>
 <?php
 // Start the Loop
 while (have_posts()) : the_post();
 ?>
 <entry>

<title><![CDATA[<?php the_title_rss() ?>]]></title>
 <link href="<?php the_permalink_rss() ?>" />
 <published><?php echo get_post_time('Y-m-d\TH:i:s\Z'); ?></published>
 <content type="html"><![CDATA[<?php the_content() ?>]]></content>
 </entry>
 <?php
 // End of the Loop
 endwhile ;
 ?>
</feed>

 <?php
}
?>

Code snippet boj_addfeed/plugin.php