Lumberjack has a built-in query builder which provides an expressive, fluent and explicit way of querying data in WordPress. It can be used instead of WP_Query to query posts (of any type) and means you do not have to worry about "the loop".
There are 2 ways in which you can use the query builder. Either on a Post Type:
1
useApp\PostTypes\Project;
2
​
3
$projects= Project::builder()
4
->orderBy('date','asc')
5
->get();
Copied!
Or by using the query builder directly:
1
useApp\PostTypes\Project;
2
useApp\PostTypes\CaseStudy;
3
useRareloop\Lumberjack\QueryBuilder;
4
​
5
$posts=(newQueryBuilder)->wherePostType([
6
Project::getPostType(),
7
CaseStudy::getPostType(),
8
])
9
->orderBy('date','asc')
10
->get();
Copied!
Using the query builder on a Post Type
This is the most common way to use the query builder. You can start querying posts simply by using the Rareloop\Lumberjack\Post class. To start a query, use the builder() method.
1
Post::builder();
Copied!
This creates an instance of Rareloop\Lumberjack\ScopedQueryBuilder. This class does a couple of important things:
Returns the correct post objects
When querying a post type, you will always get the same post object back in your results rather than WP_Post objects.
For example, if you have a custom post type called Employee, when you query employees you will always get Employee objects back as results. Lets see what this looks like:
1
useApp\PostTypes\Employee;
2
​
3
$employees= Employee::builder()->get();
4
​
5
dump($employees);
6
​
7
/*
8
Collection {
9
#items: array:2 [
10
0 => App\PostTypes\Employee,
11
1 => App\PostTypes\Employee,
12
]
13
}
14
*/
Copied!
The collection contains instances of the Employee class. This is extremely powerful as you now have access to all the behaviours that come with employees, as defined in your post type class. In this case, you may have a photoUrl() method on an Employee that knows (encapsulates) how to get the correct size image from the featured image:
1
classEmployeeextendsPost
2
{
3
...
4
​
5
publicfunctionphotoUrl(): string
6
{
7
$thumbnail=$this->thumbnail();
8
​
9
if(empty($thumbnail)){
10
returnnull;
11
}
12
​
13
return$thumbnail->src('large');
14
}
15
}
Copied!
And when iterating through your results, you can safely use this photoUrl() method:
1
useApp\PostTypes\Employee;
2
​
3
$employees= Employee::builder()->get();
4
​
5
$employee=$employees->first();
6
​
7
// This will echo out the featured image url if there is one
8
echo$employee->photoUrl();
Copied!
All post types extend Timber's Post object, so you get access to all of their behaviour out of the box.
The example above is making use of Timber's thumbnail() method on a Post, and src() method on an Image.
If collections are new to you, be sure the check out the documentation on them:
Sometimes you will need to perform the same filter on a query in multiple places within your theme.
1
// Get all featured posts, newest first
2
$featuredPostIds=[1,2];
3
​
4
$posts= Post::whereIdIn($featuredPostIds)
5
->orderBy('date','desc')
6
->get();
7
​
8
...
9
​
10
// Get the latest 3 featured posts
11
$featuredPostIds=[1,2];
12
​
13
$posts= Post::whereIdIn($featuredPostIds)
14
->orderBy('date','desc')
15
->limit(3)
16
->get();
Copied!
In this example, we are scoping the query to only show featured images. However there's 2 issues with this:
1.
We doing it twice, without reusing any code
2.
It can be unclear as to what you are doing
Instead, We can encapsulate the knowledge about how to find featured posts by creating a query scope on our post type:
1
namespaceApp\PostTypes;
2
​
3
useRareloop\Lumberjack\Postas LumberjackPost;
4
​
5
classPostextendsLumberjackPost
6
{
7
...
8
​
9
publicfunctionscopeFeatured($query)
10
{
11
$featuredPostIds=[1,2];
12
​
13
return$query->whereIdIn($featuredPostIds);
14
}
15
}
Copied!
Now we have a query scope, we can refactor our previous queries, making them more declarative and easier to change:
1
// Get all featured posts, newest first
2
$posts= Post::featured()
3
->orderBy('date','desc')
4
->get();
5
​
6
...
7
​
8
// Get the latest 3 featured posts
9
$posts= Post::featured()
10
->orderBy('date','desc')
11
->limit(3)
12
->get();
Copied!
Query scopes must start with the word scope, and must follow with the name of the method you want available to the builder. The method should also be defined in CamelCase. For example:
scopeFoo() will allow you to call foo() on a query.
scopeFooBar() will allow you to call fooBar() on a query.
You can also pass through parameters into the query scope:
1
namespaceApp\PostTypes;
2
​
3
useRareloop\Lumberjack\Postas LumberjackPost;
4
​
5
classPostextendsLumberjackPost
6
{
7
...
8
​
9
publicfunctionscopeExclude($query,$postId)
10
{
11
return$query->whereIdNotIn([$postId]);
12
}
13
}
14
​
15
...
16
​
17
// Get all featured posts, newest first, excluding post id 1
18
$posts= Post::exclude(1)
19
->orderBy('date','desc')
20
->get();
Copied!
Available methods
All the available methods can be chained, with the exclusion of getParameters and get.
This method can either take an array of statuses, or multiple parameters for each status:
Array of statuses:
Parameters
Type
Description
$statuses
array
An array of statuses. e.g. publish or draft
1
$query->whereStatus(['publish','draft']);
Copied!
Multiple parameters:
Parameters
Type
Description
$status
string
A status. e.g. publish or draft
$status
string
A status. e.g. publish or draft
...
...
...
1
$query->whereStatus('publish','draft');
Copied!
Scope the query to only include posts with the given status. By default WordPress will only look for published posts, so you only need to use this method if you need to get posts with other statuses.
Sorting will be alphabetical for strings. When dealing with numbers, you can get some unexpected results (e.g. 1, 3, 34, 4, 56, 6, etc, rather than 1, 3, 4, 6, 34, 56 as you might naturally expect).
​
Pass in 'numeric' here if you plan on sorting numbers.
Sets the orderby argument for WP_Query to meta_value when ordering strings, and meta_value_num when ordering numbers.
The name of the post class that you want the results transformed to
When using WP_Query, you get an array of WP_Post objects back. The query builder will instead return an array of Rareloop\Lumberjack\Post objects back.
You can use this method to change what object is returned from the query builder.
1
useApp\PostTypes\Event;
2
​
3
// Get an array of Event objects back
4
$query->wherePostType('event')
5
->as(Event::class)
6
->get();
Copied!
Note: When using the query builder on a post type, this conversion is done automatically. For example:
The Lumberjack QueryBuilder class can be extended with custom functionality at runtime (the class is "macroable"). The following example adds a search method to the QueryBuilder class that can be used to filter results based on a keyword search: