Making queries
With queries, you can easily filter, retrieve and delete multiple entries from the database. To keep things simple, HivePress implements a common API for all the WordPress query types (e.g.
WP_Query
, WP_Comment_Query
, WP_Term_Query
).Let's take a look at the main query operations. We use the
Listing
model in the examples below, but the API is the same for all models. You can always check the available models in the includes/models
subdirectory of HivePress or its extensions.The code example below gets three featured listings from a specific category and orders them by the creation date. Then each listing is updated with the "Custom text" title, and finally, all listings are deleted.
// Query listings.
$listings = HivePress\Models\Listing::query()->filter(
[
'featured' => true,
'categories__in' => [ 123 ],
]
)->order( [ 'created_date' => 'desc' ] )
->limit( 3 )
->get();
// Update listings.
foreach ( $listings as $listing ) {
$listing->set_title( 'Custom text' )->save_title();
}
// Delete listings.
$listings->delete();
To create a query object, call the static
query
method on the HivePress\Models\{Model_Name}
class:$query = HivePress\Models\Listing::query();
After the object is created, you can start building the query. Please note that the database will not be queried until you call one of the methods for retrieving results.
For filtering the results, call the
filter
method with an array where keys are field names and values are used for comparison:$query->filter(
[
'status' => 'publish',
'verified' => true,
]
);
The default comparison operator is
=
, but the following operators are also available:not
(!=)gt
(>)gte
(>=)lt
(<)lte
(<=)like
not_like
in
not_in
between
not_between
exists
not_exists
To use the comparison operator, add it to the field name via the double underscore:
// Filter listings by ID.
$query->filter(
[
'id__in' => [ 1, 2, 3 ],
]
);
// Filter listings with rating > 3.
$query->filter(
[
'rating__gt' => 3,
]
);
// Filter listings with an image.
$query->filter(
[
'image__exists' => true,
]
);
Also, you can use the
search
method to search results. For example, the code below searches listings with the "foobar" word in the listing title or description:$query->search( 'foobar' );
Since HivePress doesn't fully replace the WordPress query API, you may need to set some WordPress-level arguments depending on the underlying query type (e.g.
WP_Query
). To do this, simply call the set_args
method with an array of the WordPress-level query arguments:$query->set_args(
[
'meta_key' => 'custom_field',
'meta_value' => 123,
]
);
Similarly, if you build a query object with the HivePress API, you can get an array of WordPress-level query arguments using the
get_args
method (e.g. for passing to WP_Query
):$args = $query->get_args();
To order the query results, call the
order
method with an array where keys are field names and values define the sorting order (asc
for ascending, desc
for descending):$query->order( [ 'created_date' => 'desc' ] );
If you filter results by ID and want them to follow the same order, pass the
id__in
argument:$query->order( 'id__in' );
Also, if the query model inherits the
Post
class, you can set a random order:$query->order( 'random' );
To limit the number of results, use the
limit
method:$query->limit( 123 );
For retrieving results starting from a specific position, call the
offset
method:$query->offset( 123 );
To paginate results based on the limit, use the
paginate
method with the page number:$query->paginate( 123 );
Once the query is ready, call the
get
method to retrieve entries from the database:$listings = $query->get();
It returns an array-like object that you can iterate over (e.g. with
foreach
loop) or check the result count using the count
method. If you need a regular array, call the serialize
method:$listings = $listings->serialize();
Also, you can chain query methods for better code readability:
$listings = $query->get()->serialize();
To get the IDs only, use the
get_ids
method instead:$listing_ids = $query->get_ids();
For the first result only, call the
get_first
method:$listing = $query->get_first();
To get its ID only, use the
get_first_id
method:$listing_id = $query->get_first_id();
To get the result count only, call the
get_count
method instead:$listing_count = $query->get_count();
For retrieving a single result by ID, call the
get_by_id
method directly:$listing = HivePress\Models\Listing::query()->get_by_id( 123 );
Currently, there's no method for updating results in bulk, but you can iterate over the model objects and update them separately:
foreach ( $listings as $listing ) {
$listing->fill(
[
'title' => 'Custom title',
'featured' => true,
]
)->save( [ 'title', 'featured' ] );
}
To delete the query results from the database, call the
delete
method:$query->delete();
Also, if the query model inherits the
Post
or Comment
classes, you can move results to Trash:$query->trash();
For deleting a single result without retrieving it, call the
delete_by_id
method directly:HivePress\Models\Listing::query()->delete_by_id( 123 );
Last modified 1yr ago