Queries / Introduction

We make WordPress queries easy to understand, readable, and fun to write. I know that's saying a lot as WordPress' native query interface, via get_posts or WP_Query, is just terrible. We wrap all that garbage up behind a tidy interface called q. I guarantee you're going to love it.

q wraps WordPress' wp_posts and WP_Query calls. So tell q what you want and it writes the yucky WordPress code for you. Let's do a couple of quick examples to show legibility and speed.

/*
 * Examples assuming we have a Post Type for "albums" and a taxonomy
 * for this post type with the slug of "genre"
 */
// Simple
// when we write the following
$albums = wpm('q.album')->tax('genre', 'jazz')->limit(3)->get();

// behind the scenes, q builds a query like...
return get_posts([
    'posts_per_page' => 3,
    'orderby' => 'post_date',
    'order' => 'desc',
    'post_type' => [
        'album'
    ],
    'post_status' => 'publish',
    'suppress_filters' => 1,
    'tax_query' => [
        [
            'taxonomy' => 'genre',
            'field' => 'slug',
            'terms' => ['jazz'],
            'operator' => 'IN',
            'include_children' => 1
        ]
    ]
]);

We'll get into more complex queries later but I wanted to quickly go over why this is better. With q we can write a simple, readable, single line of code to get what we need.

Instead of abstract key/value pairs jammed into an array, you can create a query that is almost in sentence form.

// hey q, from   album, with a genre of jazz,  I need 3,  get em
$albums = wpm('q.album')->tax('genre', 'jazz')->limit(3)->get();

With q all queries begin with a post type. To select a Post Type for querying add it just after the q..

// select the "member" Post Type
$members = wpm('q.member')->get();

// select the "client" Post Type
$clients = wpm('q.client')->get();

It is also possible to select multiple Post Types. Limitations to defining multiple Post Types in get_posts or WP_Query will apply here.

$results = wpm('q.member|client')->get();

We can make queries by chaining methods together. With chaining, we can create complexity by add additional criteria with continuous method calls linked together with ->. We'll go over all the chainable methods in the next chapter of the docs.

/*
 * Simplest Chain
 * Get all the furniture
 */
$furniture = wpm('q.furniture')->get();

/*
 * Simple Chain
 * Get no more than 10 pieces of furniture with a height of 40
 */
$furniture = wpm('q.furniture')->meta('height', 40)->limit(10)->get();

/*
 * Intermediate Chain
 * Get all furniture that is in the kitchen and dining rooms, OR is a type of table
 * and has a height of 30 or more and a width of 20 or less
 */
$furniture = wpm('q.furniture')
    ->tax('room', ['kitchen', 'dining'])
    ->orTax('type', 'table')
    ->meta('height', '>=', 30)
    ->andMeta('width', '<=', 20)
    ->get();

/*
 * More Complex Chain
 * Get all furniture for the kitchen and dining rooms,
 * OR is a type of table,
 * has width of 40 or more, length of 40 or more, and height less than 30
 * OR has a width of 30 or less, and a length of 30 or less
 */
$furniture = wpm('q.furniture')
    ->tax('room', ['kitchen', 'dining'])
    ->orTax('type', 'table')
    ->meta(function($wpm) {
        return [
            'relation' => 'AND',
            $wpm->metaQuery('width', '>=', 40),
            $wpm->metaQuery('length', '>=', 40),
            $wpm->metaQuery('height', '<',  30)
        ];
    })
    ->orMeta(function($wpm) {
        return [
            'relation' => 'AND',
            $wpm->metaQuery('width', '<=', 30),
            $wpm->metaQuery('length', '<=', 30)
        ];
    })
    ->get();

Now that we can make our super cool queries we need to get the results back. In our examples so far we've used ->get() but <yoda-voice>there is anothers</yoda-voice>. Let's define each.

->get()

As you've seen, get returns all results that meet the criteria defined by our query. These results are returned as an array of objects. WPM will always deliver objects. These objects include related data in an easy-to-use package. Read more about this in the Results Data portion of the docs.

// if there are 10 members...
$members = wpm('q.member')->get();  // get all

echo count($members);               // will print 10

// if there are 3 named "Larry"
$members = wpm('q.member')
    ->search('Larry')               // name stored in post_title
    ->get();

echo count($members);               // will print 3
echo $members[0]->post_title;       // will print the post title of the first result

By default, WPM creates does a get_posts call behind the scenes. You can alternately use pass true into the get method to return a new WP_Query instead.

$wp_query = wpm('q.member')->get(true);

->first()

first returns the very first result object that matches a query's criteria.

// if there are 10 members...
$member = wpm('q.member')->first();  // get first

echo $member->ID;                    // print result ID

// if there are 3 named "Larry"
$member = wpm('q.member')
    ->search('Larry')               // name stored in post_title
    ->first();

echo $member->post_title;           // print result post_title

->find()

find will return a custom post type for a given id or slug passed in as an argument. Unlike get and first, find does not use chained methods.

// find a post with the id of 1
$post = wpm('q.post')->find(1);

// find a member with the slug of "alexander-hamilton"
$hammy = wpm('q.member')->find('alexander-hamilton');

->getArgs()

WPM makes creating a complex query simple but sometimes you may want to check what it is doing for you behinds the scenes. To do this, use getArgs to take a look all the arguments that have been assembled to make your query possible.

echo '<pre>';
print_r(
    wpm('q.album')->tax('genre', 'jazz')->limit(3)->getArgs()
);
echo '</pre>';