Search Over 30,000 FREE Plugins from the Official WordPress Plugin Directory Repository

Inject Query Posts

Inject an array of posts into a WP query object as if queried, particularly useful to allow use of standard template tags.

WordPress's template tags are intended to be used within 'the loop'. The loop is managed by a WP_Query object which sets up various global variables and its own object variables for use by the various template tags. The primary purpose of a WP_Query object is to actually query the database for the posts that match the currently specified criteria. However, if you don't need to query for posts since you already have them by some other means, you can still take advantage of the template tags by injecting those posts into the WP_Query via this plugin.

Depending on the template tags you are looking to use, or the logic you are hoping to employ within a loop, you may need to manually configure some of the query object's variables.


<?php // Say we're in the sidebar

// We've gotten some post objects on our own.
$posts = c2c_get_random_posts( 5, '' );

// Inject the posts
c2c_inject_query_posts( $posts );

// Now let's display them via template tags:
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>

        <li><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></li>

    <?php endwhile;?>
<?php endif; ?>

Links: Plugin Homepage | Plugin Directory Page | Author Homepage

Author Scott Reilly
Contributors coffee2code
Tags coffee2code, loop, posts, query, template tags, WP_Query
  1. Install via the built-in WordPress plugin installer. Or download and unzip inside the plugins directory for your site (typically wp-content/plugins/)
  2. Activate the plugin through the 'Plugins' admin menu in WordPress
  3. Use the c2c_inject_query_posts() function to inject an array of posts into a WP query object. Specify the posts array as the first argument. Configure the query object by passing an array as the second argument. If specifying a WP query object, pass it as the third object; if not specified then the global wp_query object will be assumed.

2.2.5 (2017-02-03)

  • Change: Default WP_TESTS_DIR to /tmp/wordpress-tests-lib rather than erroring out if not defined via environment variable.
  • Change: Enable more error output for unit tests.
  • Change: Minor unit test improvements.
  • Change: Note compatibility through WP 4.7+.
  • Change: Minor readme.txt improvements.
  • New: Add LICENSE file.
  • Change: Update copyright date (2017).

2.2.4 (2016-01-25)

  • New: Create empty index.php to prevent files from being listed if web server has enabled directory listings.
  • New: Add 'Text Domain' header attribute.
  • Change: Note compatibility through WP 4.4+.
  • Change: Explicitly declare methods in unit tests as public.
  • Change: Update copyright date (2016).

2.2.3 (2015-08-14)

  • Bugfix: 'c2c_inject_query_posts' hook should be a filter and not an action
  • Update: Correct documentation regarding 'c2c_inject_query_posts' hook
  • Update: Minor inline document tweaks (spacing)
  • Update: Add full inline documentation to provided example
  • Update: Note compatibility through WP 4.3+

2.2.2 (2015-02-11)

  • Note compatibility through WP 4.1+
  • Update copyright date (2015)

2.2.1 (2014-08-25)

  • Minor plugin header reformatting
  • Minor code reformatting (spacing, bracing)
  • Change documentation links to to be https
  • Note compatibility through WP 4.0+
  • Add plugin icon

2.2 (2013-12-17)

  • Change default of $preserve_query_obj argument to false, meaning that the query object getting injected will be reset before doing so
  • Remove manual resetting of WP_Query variables since the class's init() does it all
  • Support passing a WP_Post object as the first argument
  • Add unit tests
  • Note compatibility through WP 3.8+
  • Drop compatibility with versions of WP older than 3.6
  • Update copyright date (2014)
  • Add banner
  • Change donate link
  • Minor code formatting changes (bracing)
  • Minor formatting changes (spacing) and code example changes in readme.txt


  • Rename inject_query_posts() to c2c_inject_query_posts() (but maintain a deprecated version for backwards compatibility)
  • Add filter 'c2c_inject_query_posts' so that users can use the do_action('c2c_inject_query_posts') notation for invoking the function
  • Add optional $cache_posts argument to function and use it determine if update_post_caches() should be called
  • Add better control for specifying arguments to update_post_caches()
  • Send $posts and $config as additional args to 'inject_query_posts_preserve_query_obj' filter
  • Add check to prevent execution of code if file is directly accessed
  • Update documentation
  • Note compatibility through WP 3.5+
  • Update copyright date (2013)


  • Re-license as GPLv2 or later (from X11)
  • Add 'License' and 'License URI' header tags to readme.txt and plugin file
  • Remove ending PHP close tag
  • Note compatibility through WP 3.4+


  • Note compatibility through WP 3.2+
  • Add link to plugin directory page to readme.txt
  • Update copyright date (2012)


  • Remove unnecessary reset of meta_query and tax_query query object variables


  • Note compatibility through WP 3.2+
  • Minor code formatting changes (spacing)
  • Fix plugin homepage and author links in description in readme.txt


  • Note compatibility through WP 3.1+
  • Update copyright date (2011)


  • If no query_obj is sent, use the global $wp_query object (previously used to create a new query object)
  • If a not-false, non-object value is sent as $wp_query object (namely any non-empty string or non-zero integer), then create a new WP_Query object for use
  • Add ability to preserve the state of the existing query_obj
    • Add $preserve_query_obj arg (optional) to inject_query_posts(), default to true
    • Add filter 'inject_query_posts_preserve_query_obj' that gets passed value of $preserve_query_obj
  • Reset more query_obj settings
  • Wrap function in if(!function_exists()) check
  • Remove docs from top of plugin file (all that and more are in readme.txt)
  • Minor code reformatting (spacing)
  • Add PHPDoc documentation
  • Note compatibility with WP 2.8+, 2.9+, 3.0+
  • Update copyright date
  • Add package info to top of plugin file
  • Add Changelog, Filters, Template Tags, and Upgrade Notice sections to readme.txt
  • Remove trailing whitespace
  • Add to plugin repo


  • Initial release

Template Tags

The plugin provides one template tag for use in your theme templates, functions.php, or plugins.


  • <?php function c2c_inject_query_posts( $posts, $config = array(), $query_obj = null, $preserve_query_obj = true, $cache_posts = true ) ?> Injects an array of posts into a query object as if that query object had obtained those posts via a query.


  • $posts (array) Array of posts to inject into the query object.

  • $config (array) Optional. Associative array of query object variables to directly set, and their values.

  • $query_obj (WP_Query|null) Optional. The query object to modify. If null, then the global wp_query object will be used. Pass a string or non-zero integer to have a new query object created and used.

  • $preserve_query_obj (bool) Optional. Should the query object be kept as-is prior to injecting posts? Default is false. If false, then the object is re-initialized/reset before post injection.

  • $cache_posts (bool) Optional. Update the posts in cache? Default is true.


  • (See Description section for an additional example.)

  • Similar to previous example, for WP 3.0+

$posts = c2c_get_random_posts( 5, '' ); // Obtain posts via your favorite related posts, find posts, etc plugin, or via custom query
do_action( 'c2c_inject_query_posts', $posts ); // Better than direct call to c2c_inject_query_posts( $posts );
get_template_part( 'loop' );


The plugin is further customizable via two hooks. Such code should ideally be put into a mu-plugin or site-specific plugin (which is beyond the scope of this readme to explain).

inject_query_posts_preserve_query_obj (filter)

The 'inject_query_posts_preserve_query_obj' filter allows you override the value of the $preserve_query_obj argument passed to the function. This is not typical usage for most users.


  • $preserve_query_obj (bool) : Boolean indicating if the query object was set to be preserved or not
  • $query_obj (WP_Query object) : The WP_Query object passed to the c2c_inject_query_posts()
  • $posts (array) : The posts being injected into the WP_Query object
  • $config (array) : Query object variables to directly set, and their values.


 * Always preserve the condition of the WP_Query object passed ot Inject Query Posts.
 * @param bool     $preserve_query_obj The default preservation value as passed to the function.
 * @param WP_Query $query_obj          The query object.
 * @param array    $posts              The posts being injected.
 * @param array    $config             Associative array of query object variables to directly set, and their values.
 * @return bool
function my_preserve_query_obj( $preserve_query_obj, $query_obj, $posts, $config ) {
    return true;
add_filter( 'inject_query_posts_preserve_query_obj', 'my_preserve_query_obj', 10, 4 );

c2c_inject_query_posts (filter)

The 'c2c_inject_query_posts' filter allows you to use an alternative approach to safely invoke c2c_inject_query_posts() in such a way that if the plugin were deactivated or deleted, then your calls to the function won't cause errors in your site.


  • The same arguments as c2c_inject_query_posts()


Instead of:

<?php echo c2c_inject_query_posts( $posts, array( 'is_search' => true ) ); ?>


<?php echo apply_filters( 'c2c_inject_query_posts', $posts, array( 'is_search' => true ) ); ?>
Version 2.2.5

Requires WordPress version: 3.6 or higher

Compatible up to: 4.7.2

Last Updated 13 Feb 2017

Date Added: 27 Sep 2010

Plugin Homepage


0 stars
0 ratings


Not Enough Data

Works: 0
Broken: 0