README

A generator function that makes working with the WordPress loop a dream.

When will this land in WordPress core?

At the moment, that is unclear. However, you can follow the progress of this trac ticket.

Installation

• Run composer require wp-forge/wp-loop
• Make sure you require the vendor/autoload.php file in your project.

Usage

Here are a few examples of how to use the wp_loop() function:

With the Global WP_Query Instance

<?php

foreach ( wp_loop() as $post ) {
	?>
	<article>
		<h1><?php the_title(); ?></h1>
		<div><?php the_content(); ?></div>
	</article>
	<?php
}

With a Custom WP_Query Instance

<?php

$query = new WP_Query( [ 'post_type' => 'post' ] );

foreach ( wp_loop( $query ) as $post ) {
	?>
	<article>
		<h1><?php the_title(); ?></h1>
		<div><?php the_content(); ?></div>
	</article>
	<?php
}

There is no need to run wp_reset_postdata() after the loop. It is taken care of automatically, even if you break out of the loop early!

With an Array of WP_Post Objects

<?php

$query = new WP_Query( [ 'post_type' => 'post' ] );
$posts = $query->posts;

foreach ( wp_loop( $posts ) as $post ) {
	?>
	<article>
		<h1><?php the_title(); ?></h1>
		<div><?php the_content(); ?></div>
	</article>
	<?php
}

With an Array of Post IDs

<?php

$query = new WP_Query( [
	'post_type' => 'post',
	'fields'    => 'ids',
] );

$post_ids = $query->posts;

foreach ( wp_loop( $post_ids ) as $post ) {
	?>
	<article>
		<h1><?php the_title(); ?></h1>
		<div><?php the_content(); ?></div>
	</article>
	<?php
}

With an Iterator

<?php

$query    = new WP_Query( [ 'post_type' => 'post' ] );
$iterator = new ArrayIterator( $query->posts );

foreach ( wp_loop( $iterator ) as $post ) {
	?>
	<article>
		<h1><?php the_title(); ?></h1>
		<div><?php the_content(); ?></div>
	</article>
	<?php
}

Other Notes

The wp_loop() function is meant to be used in a foreach loop. If you need to check if there are results before looping, you can do that the way you normally would.

For example:

<?php

if( have_posts() ) {
    // For global query approach
}

if( $query->have_posts() ) {
    // For custom query approach
}

if( ! empty( $posts ) ) {
    // For post or post ID approach
}

if( $iterator->valid() ) {
    // For iterator approach
}

The wp_loop() function goes one step further than the standard WordPress loop does and automatically sets and restores the global $post object for each iteration.

For more details, read this blog post on Creating a Better WordPress Loop. The current implementation is a bit different, but the reasoning is laid out quite well.