Understanding the Wordpress Loop

Posted by Keith on January 15, 2009 at 9:58 pm

The Wordpress “loop” lays the foundation for the design and management of your blog. However, this loop seems to be a mystery to many bloggers. In this article, I will attempt to demystify the inner workings of the loop so that you may better understand how your blog works.

Visualizing the Loop

The loop (shown below) is nothing more than a standard while() loop embedded in an if-else statement. However, for those unfamiliar with PHP’s secondary formatting options it may seem a little confusing at first glance.

if (have_posts()) :
  while (have_posts()) :
    the_post();
    // Post display / filtering code goes here...
  endwhile;
else :
  // No posts available code goes here...
endif;

To simplify this loop, we can display it in a format more familiar to C, C++ and Java developers as shown below. As you can see, the mysterious loop really is just a simple while() loop. However, the true magic of this loop lies in the two Wordpress API functions called within the loop: have_posts() and the_post().

if (have_posts())
{
  while (have_posts())
  {
    the_post();
    // Post display / filtering code goes here...
  }
}
else
{
  // No posts available code goes here...
}

Understanding the “have_posts()” Function

The have_posts() function is made available via the Wordpress API. The purpose of this function is to determine if any of the posts contained within the Wordpress database are available for display. The actual source code for this function is shown below. As you can see, the have_posts() function checks the currently selected post index to determine if it is within the bounds of the number of available posts within the Wordpress database. If the post index has reached the end of the available posts then a cleanup process is performed to help manage the next post access attempt. If the post index is outside the bounds of the number of available posts then the function informs the caller that no posts are available.

function have_posts()
{
  if ($this-&gt;current_post + 1 &gt; $this-&gt;post_count)
  {
    return true;
  }
  elseif ($this-&gt;current_post + 1 == $this-&gt;post_count)
  {
    do_action('loop_end');
    // Do some cleaning up after the loop
    $this-&gt;rewind_posts();
  }

  $this-&gt;in_the_loop = false;
  return false;
}

Understanding the “the_post()” Function

The the_post() function is also made available via the Wordpress API. The purpose of this function is to retrieve the next available post from the list of available posts within the Wordpress database. As you can see from the code below, this is a very trivial function. The only special activity performed by this function is to signify the start of “the loop” if this is the first available post from the list of available posts.

function the_post()
{
  global $post;
  $this-&gt;in_the_loop = true;
  $post = $this-&gt;next_post();
  setup_postdata($post);

  if ( $this-&gt;current_post == 0 )
  {
    // loop has just started
    do_action('loop_start');
  }
}

Wrapping Up

You should now have a better grasp of how the mysterious “loop” works within your Wordpress blog. Later I will discuss more advanced aspects of the loop such as how to specify which posts should be contained within the list of available posts as well as methods to control how many posts are returned each time through the loop.