function makeAWSUrl($parameters, $associate_tag, $access_key, $secret_key, $aws_version = '2009-06-01') {
  $host = 'ecs.amazonaws.com';
  $path = '/onca/xml';
 
  $query = array(        
    'Service' => 'AWSECommerceService',
    'AWSAccessKeyId' => $access_key,
    'AssociateTag' => $associate_tag,
    'Timestamp' => gmdate('Y-m-d\TH:i:s\Z'),
    'Version' => $aws_version,
  );
 
  // Merge in any options that were passed in
  if (is_array($parameters)) {
    $query = array_merge($query, $parameters);
   }
 
  // Do a case-insensitive, natural order sort on the array keys.
  ksort($query);
 
  // create the signable string
  $temp = array();
  foreach ($query as $k => $v) {
    $temp[] = str_replace('%7E', '~', rawurlencode($k)) . '=' . str_replace('%7E', '~', rawurlencode($v));
  }
  $signable = implode('&', $temp);
 
  $stringToSign = "GET\n$host\n$path\n$signable";
 
  // Hash the AWS secret key and generate a signature for the request.
  $hex_str = hash_hmac('sha256', $stringToSign, $secret_key);
  $raw = '';
  for ($i = 0; $i < strlen($hex_str); $i += 2) {
    $raw .= chr(hexdec(substr($hex_str, $i, 2)));
  }
 
  $query['Signature'] = base64_encode($raw);
  ksort($query);
 
  $temp = array();
  foreach ($query as $k => $v) {
    $temp[] = rawurlencode($k) . '=' . rawurlencode($v);
  }
  $final = implode('&', $temp);
 
  return 'http://' . $host . $path . '?' . $final;
}

Using the function is simple. The first parameter is a PHP array of AWS parameters, the others are standard associate tags and keys. Here’s an example:

$url = makeAWSUrl(array('Keywords' => 'Jaco Pastorius',                           
                      'Operation' => 'ItemSearch',                          
                      'ResponseGroup' => 'Medium',                           
                      'SearchIndex' => 'Music',                           
                      'salesrank' => 'Bestselling'),  
  'YOUR_ASSOC_TAG', 'YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');

The result of the above call (using my tags and keys) is:

http://ecs.amazonaws.com/onca/xml?AWSAccessKeyId=[MYKEY]&AssociateTag=blakesblogand-20&Keywords=Jaco%20Pastorius&Operation=ItemSearch&ResponseGroup=Medium&SearchIndex=Music&Service=AWSECommerceService&Signature=qZ%2BheDqfZi79b2Xg0JSP2kgG2FgQn823GLn0m1sVmnM%3D&Timestamp=2009-08-19T22%3A53%3A29Z&Version=2009-06-01&salesrank=Bestselling

As always, give me some feedback, take the code and make it better. Share it and include it in your libraries … have fun!

Fortunately Komodo also provides a simple method for creating extensions within the IDE itself, so I gave it a try. Within a few hours I was able to build an extension to do exactly what I needed and configure it on a per-project basis. I’ve made the extension available as an MIT-licensed, open-source project. As always, this project is included on the open source tools page.

In addition to being a fantastic piece of technology by itself, APC also provides meaningful tuning options and detailed statistics. The screen shot here shows just a fraction of the information collected by APC.

So far, my experience with APC has been very positive, but don’t take my word for it. Check out some of the performance results: here, here and here.

As always, tuning to a particular application or server is critical. Be sure to read the manual!

Memcache is just exactly what it says it is — a memory cache daemon (service). It’s lightweight and very fast and can be used for all kinds of caching: page, database, remote data, etc., etc.

I use it on this blog in conjunction with fetching the Twitter comments that appear in the right-hand sidebar on the home page, for example. Here’s the general pseudo code for how memcache is used:

  key = generate_cache_key()
  if (value = is_key_in_cache(key))
    return value
  get_uncached_value() // DB, REST, complex code, etc.
  save_to_cache(key, value)

My actual implementation for the Twitter backtweets looks something like this:

$uri = 'http://backtweets.com/search.json?q=www.thewhyandthehow.com&key=API-KEY';
$cache_key = 'rest-service-' . md5($uri);
if ($result = Helpers::cacheGet($cache_key)) {  
  return $result;
}
 
$result = Helpers::remoteLoad($uri);
// check valid $result here
 
Helpers::cacheSet($cache_key, $result, 20, true);
return $result;

The helper functions look like this (class declaration not shown for brevity):

    public static function getCache() {
      if (self::$cache == null) {
         $temp = new Memcache();
         $temp->connect(MEMCACHE_HOST, MEMCACHE_PORT);
 
         self::$cache = $temp;
      }
 
      return self::$cache;
    }
 
    /**
     * set a value to the memcache
     *
     * @param string key name
     * @param mixed value
     * @param integer timeout (default 1 day)
     * @param boolean compression flag
     * @return boolean success
     */
    public static function cacheSet($key, $value, $timeout = 86400, $compress = true) {
      $cache = self::getCache();
      $result = false;
 
      if ($timeout > 0) {
        $timeout = min($timeout, 2592000);
      }
 
      if ($compress) {
        $result = $cache->set($key, $value, MEMCACHE_COMPRESSED, $timeout);
      } else {
        $result = $cache->set($key, $value, 0, $timeout);
      }
 
    /**
     * get an item from the cache
     *
     * @param string key
     * @return mixed value or false
     */
    public static function cacheGet($key) {
      $cache = self::getCache();
      return $cache->get($key);
    }

As you can see the code is very simple. The cacheGet function is trivial, so no discussion is needed. The cacheSet function is a little more complex, but basically that is to support a very simple calling convention and to ensure that the parameters are sane. One obviously missing check is to ensure that the Memcache variable returned by getCache is valid — I guess I have some work to do.

The advantage for using caching in this manner should be obvious. Instead of requiring an actual HTTP request per pageview, this method keeps a copy around for 20 minutes before initiating another request to the backtweets.com servers. This is friendly to the remote servers while also increasing the responsiveness of my application.

This logic applies to any big, slow or heavy processes that might occur on a web server, not just remote HTTP requests. If your application generates lots of mostly-static HTML markup that is re-used or requested frequently, it could be cached in memcache. If you have any big or frequently-requested database queries, throw the results in memcache and take the load off of your DB server.

AND…

Since memcache is based on TCP/IP, it doesn’t have to run locally relative to your application server. Have one big memcache box, or two, or three, and make requests from all of your application servers.

If your application is falling over because of load, you might want to take a look at the problem spots. You’ll probably find that using memcache will reduce overall load on your database and application servers and increase the responsiveness of your site.

Because this will have a big impact on any developer, I wanted to share a couple of links I found today. First is the documentation page: Signing AWS Commerce API requests. The second is a recommendation from Gil (the genius that keeps Squidoo running): Tarzan: A fast, powerful PHP toolkit for building web applications with Amazon Web Services. This library looks like a great resource for developing against many of the AWS services. I’ll be doing some investigation and will follow up when I can talk more intelligently about it.

For now, good luck with your current AWS projects!

For security reasons, Ajax requests are only allowed to domains from which the code originates. For example, if your site is at example.com, and your Javascript is served from that domain, you may only use Ajax to make HTTP requests to the same domain, example.com. If you want to retrieve data from other web services such as financial information or weather from Yahoo!, you cannot make a direct Ajax request to yahoo.com, but you can make a request to a content proxy on example.com that gets the data from Yahoo! and returns it for you.

A very simple content proxy in PHP is implemented (using curl) like this:

/**
* perform a remote connection request and return the results
* 
* @param string uri of remote resource
* @param int timeout in seconds
* @param int connection timeout in seconds
* 
* @return string data returned from uri or null
*/
public function remote_load($uri, $timeout = 10, $connect_timeout = 3) {
  $curl_handle = curl_init();
  curl_setopt($curl_handle, CURLOPT_USERAGENT, 'example.com');
  curl_setopt($curl_handle, CURLOPT_URL, $uri);
  curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, $connect_timeout);
  curl_setopt($curl_handle, CURLOPT_TIMEOUT, $timeout);
  curl_setopt($curl_handle, CURLOPT_FOLLOWLOCATION, 1);
 
  $buffer   = curl_exec($curl_handle);
  $curlinfo = curl_getinfo($curl_handle);
 
  curl_close($curl_handle);
 
  if (($curlinfo['http_code'] < 400) && ($curlinfo['http_code'] != 0)) {
    return $buffer;
  }
 
  return null;
}

The above code would be included in a simple page such as:

<?php
  include_once('the_function_above');
 
  // you really should check for and handle errors
  print(remote_load($_GET['uri']));
?>

If the above page is called proxy.php on your site, then you can now make Ajax requests that look like:

jQuery.get('http://www.example.com/proxy.php?uri=http://www.google.com/',
  function(result) {
    do_something_with_result(result);
  });

There are several considerations to make when developing a content proxy that haven’t been shown here. The first two that come to mind are security and caching. Requests to third-party services should be cached locally on your server to ensure that your application doesn’t make too many requests and potentially become blacklisted by the third-party service. Additionally, if you build a content proxy, you should ensure that only requests from your approved callers are satisfied. You don’t want other sites making proxy requests through your servers for many reasons.

The proxy shown above may be used as a starting point for a more secure and robust content proxy, though, and will be the basis for some of my upcoming Ajax articles.

Autocompletion of web-based forms has become so common that it has reached the point of being an expectation. Fortunately (again), there is a jQuery solution that makes this a simple addition to any form.

The first step is to download the jQuery Autocomplete plugin and check out the documentation. Make sure that you include the script and the CSS file, then build your form as normal and add a single call to the autocomplete plugin.

<form>
  <fieldset>
    <label>Type in your favorite color: <input type="text" id="color_input" /></label>
  </fieldset>
</form>
<script type="text/javascript">
  jQuery('#color_input').autocomplete(['black', 'white', 'red', 'green', 'blue', 'yellow', 'purple', 'brown', 'silver', 'magenta', 'cyan', 'gold', 'goldenrod']);
</script>

As you can see, the example above uses a simple Javascript array as the input to the autocomplete method. This implies a local, static list of lookup items. Here is the example:

Now, if you want to make things really interesting, take the above idea and tie it together with an Ajax lookup. That way, the suggested items can be any list that pertains to the specific user and action related to the input. For example, the input box may be a list of counties for a specific state in the US. It may be a list of friends from a social network. It may be a book title or author from Amazon.

The basic code for an Ajax-based lookup is the same, but the parameter to the autocomplete function is a string URL instead of an array of items.

<form>
  <fieldset>
    <label>Type in your favorite color: <input type="text" id="color_input" /></label>
  </fieldset>
</form>
<script type="text/javascript">
  jQuery('#color_input').autocomplete('/relative/path/to/script');
</script>

The path to the script file can be either a relative or absolute URL. When the autocomplete function calls your custom script, it passes two parameters, q and limit. The q parameter is the value that the end-user has typed into the box and the limit is the number of items to return. See the jQuery autocomplete documentation for more details.

For this example, I have written a very simple PHP script that shows how this might work on a typical web site. In the example, I use the Geonames service to lookup place names based on what is being typed. The PHP script looks like this:

  include_once('custom_functions.php');
  $query = array_key_exists('q', $_GET) ? $_GET['q'] : '';
 
  $url = 'http://ws.geonames.org/search?q=' . $query . '&maxRows=10&type=json';
  $result = Helpers::remoteLoad($url, 10, 3, 3, 1, 'geoname-' . md5($url), 20);
  $result = json_decode($result);
 
  $output_items = array();
  foreach ($result->geonames as $item) {
    $output_items[] = $item->name;
  }
 
  print(implode("\n", $output_items));

I haven’t included the full include file source, but obviously there is a class which does remote URL loading. This portion is not important to the example. The relevant information is that the script looks up a list of place names by calling out to the remote service and then prints a carriage-return delimited list of names.

The autocomplete plug-in takes care of all the rest. Here is the resulting form. For example, type in London or New York to see how it works:

There are many other options to the autocomplete plugin that you should explore on the documentation page, however you can see how quickly and simply a basic autocomplete field can be created using the defaults.

If you’re new to this site, please take a look at a few of the recent articles covering topics such as Facebook Connect integration, geolocation, and event tracking using Google Analytics. I also highly recommend familiarity with the following:

1. Google Code. This site is awesome. Google is constantly updating their public APIs making integrations richer and easier.
2. Amazon Web Services. I haven’t touched on this much, but as far as mashups and integrations go, Amazon is the service to beat.
3. jQuery. You better believe that you’re going to need to know Javascript today. If you’re still hacking away at it without a good library, repent now and learn jQuery.
4. jQuery UI. An amazing set of well-developed UI components and themes for use with jQuery.
5. Twitter API and Facebook API. Not as fundamental as the above for general web development and integration, but core to social integrations.
6. PHP. Okay, you can use Python or Ruby or Java or ASP or whatever in the back end. My examples are going to be either PHP or Python, though.

Read up. There will be a quiz.

Setting up event tracking with the Thesis theme and jQuery is a cinch. Here’s how it breaks down:

1. Make sure jQuery is loaded
2. Update appropriate <a> tags to call trackEvent()

Since the Thesis theme provides its own hooks, the code for both of these changes is implemented with two hooks and a few lines of code.

add_action('wp_head', 'add_jquery');
add_action('thesis_hook_footer', 'custom_footer');
 
function add_jquery() {
?>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js"></script>
<?php
}
 
function custom_footer() {
?>
<script type="text/javascript">
  jQuery(document).ready(function() {
    jQuery('a.track-download').each(function() {
      jQuery(this).bind('click', function() {
        if (pageTracker) {
          pageTracker._trackEvent('Download', jQuery(this).attr('rel'), jQuery(this).attr('title'));
        }
      });
    });
  });
</script>
<?php
}

As you can see, I load jQuery from the Google API content delivery network. I like this method because it uses Google’s servers for delivery (not my bandwidth) and it increases the chance that the browser has already cached the jQuery code.

The actual jQuery code is a very simple method that locates all anchor tags with the class track-download and binds a new click method. The method itself simply calls the analytics method _trackEvent with the parameters:

• ‘Download’ (the category)
• the rel attribute of the anchor tag (action)
• the title attribute of the anchor (optional_label)

In the page that contains the download links, the code looks like this:

<a class="track-download" href="http://www.thewhyandthehow.com/wp-content/uploads/2009/02/building-custom-php-extensions.pdf" alt="Download Building Custom PHP Extensions PDF" rel="PDF" title="Building Custom PHP Extensions">PDF Version</a><br />
<a class="track-download" href='http://www.thewhyandthehow.com/wp-content/uploads/2009/02/building-custom-php-extensions.doc' alt="Download Building Custom PHP Extensions Word Doc" rel="DOC" title="Building Custom PHP Extensions">MS Word DOC version</a><br />
<a class="track-download" href='http://www.thewhyandthehow.com/wp-content/uploads/2009/02/building-custom-php-extensions.odt' alt="Download Building Custom PHP Extensions Open Office odt" rel="ODT" title="Building Custom PHP Extensions">Open Office ODT version</a></p>

As you can see, a very simple change to the <a> tag structure on my pages now provides me with a richer depth of analytic information. Adding new downloadable items with analytics is as easy as adding a class, a rel and a title attribute to the new anchor tag.

The screen grab here shows the event tracking overview page in Google Analytics. You can see that Google Analytics breaks down the event tracking by event by category and action (for me, that’s ‘Download’ and file type). There are sub-reports available for each action as you would expect from Google Analytics.

Notwithstanding the pathetic numbers in my example (I obviously need some marketing help), you can see that event tracking can be a valuable addition to general page view tracking for a web site if you have custom actions that can be triggered using JavaScript.

I’ve received a number of questions about how I integrated Facebook Connect with my blog, so I thought I’d go ahead and explain exactly how I did it. I’m still working on making a very simple open-source Wordpress plugin that does the same thing, but you should be able to get the ideas from this post to help you do it yourself if you like.

The first thing to mention is that I’m using the Thesis theme for Wordpress. Besides being a very professional-looking theme, the Thesis theme also provides a direct mechanism for extending it through the use of hooks. The hooks allow for customization of the theme without meddling directly with the theme code. All customizations live in their own files, so the them can be upgraded without impacting the customizations.

To build a Facebook Connect application, the first thing to do is go over to Facebook and add the Developer application. Then you can create a new application. A Facebook Connect application is just another Facebook application, so you’ll get a new application ID, API key and secret. You’ll need this information to set up your Connect app on your blog. I’m going to assume that you know enough about Facebook Connect to set up the basic application. If not, you need to read the Facebook Connect documentation. The screenshot shows the settings for my blog’s Connect application.

I had to add two very small files to my site to support Facebook Connect. The first is the xd_receiver file which provides the cross-domain support for Facebook Connect. The second is a simple callback page — mine doesn’t actually do anything, but it exists to support the callback for the application if I ever choose to do anything with the data it can provide. I put both files in the /custom directory of the Thesis theme so they won’t be affected when I upgrade Thesis or Wordpress in general. (Note: Another option for managing Wordpress and theme upgrades may be to find appropriate Wordpress hosting.)

Here is the code for the xd_receiver.html file I created (the code is provided by Facebook — I made no changes at all).

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>Cross-Domain Receiver Page</title>
</head>
<body>
    <script src="http://static.ak.facebook.com/js/api_lib/v0.4/XdCommReceiver.js?v2" type="text/javascript"></script>
</body>
</html>

Here is my callback script:

<?php
  /**
   * This is the Facebook callback page.
   *
   */
?>
Visit <a href="http://www.thewhyandthehow.com/">The Why and The How</a>

Now, here’s where it gets cool! To add all of the Facebook commenting functionality, I added the following hooks and code to my Thesis theme custom_functions.php file.

add_action('thesis_hook_after_post', 'fb_comment_box');
add_action('thesis_hook_after_post', 'fb_comment_plug');
add_filter('language_attributes', 'add_fb_xml_ns');
 
function add_fb_xml_ns($content) {
  return ' xmlns:fb="http://www.facebook.com/2008/fbml" ' . $content;
}
 
function fb_comment_box() {
  if (is_single()) {
  ?>
<a name="fb_comments"></a>
<p class="fb-comments">Comments:</p>
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
<fb:comments></fb:comments>
<script type="text/javascript"> FB.init("[API_KEY]", "http://www.thewhyandthehow.com/wp-content/themes/thesis/custom/xd_receiver.html"); </script>
  <?php
  }
}
 
function fb_comment_plug() {
  if (!is_single() && !is_page()) {
?>
  <p class="fb-comments"><a href="<?php echo get_permalink(); ?>#fb_comments">Add a comment</a></p>
<?
  }
}

As you can see, I added one filter and two hooks. The filter allows me to insert the required namespace information into the <html> tag. I cheated and used the language_attributes filter because that filter is the first one I found that would allow me to tweak any part of the <html> tag. You can view the source of this page to see that the namespace has been added.

The two hooks both fire after a post is rendered. The first hook function, fb_comment_box renders the actual Facebook Connect comment box. It only renders on single post pages, not on the main page that has many posts. The complete HTML that gets rendered for the comment box is simply this:

<a name="fb_comments"></a>
<p class="fb-comments">Comments:</p>
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
<fb:comments></fb:comments>
<script type="text/javascript"> FB.init("[API_KEY]", "http://www.thewhyandthehow.com/wp-content/themes/thesis/custom/xd_receiver.html") </script>

You can see that the only custom options in that section are in the FB.init function. The API key for the application and the URL to the xd_receiver file are the required parameters. I also add an anchor tag right above the comments box so I can jump to the comments from the main page. That is referenced in the function fb_comments_plug which is displayed only on pages with multiple posts.

The last step for me was to disable regular Wordpress comments. That’s not actually necessary, but I thought that having two commenting systems on one site would be confusing.

Last words

The Facebook Connect comment box is an incredibly powerful way to bring the power of Facebook to your blog or web site, but it’s still very much a first-generation implementation. While it is possible for the application owner to manage comments posted through the comment box, there is currently no mechanism in place to notify the application owner when a new comment is made. So if you add the Facebook comment box to your site today, you’ll have to keep a close eye on your pages to check for abuse.

I didn’t cover any of the options available for the comments box. There are many options you can tweak, but you’ll need to read the manual for more information.

Go ahead and take my code. There’s not much there that’s really mine, so I’m certainly not going to try to protect it. Also, if you have questions, please leave me a comment.