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.

Quick example

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();

Creating queries

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.

Filtering 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();

Ordering results

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' );

Limiting results

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 );

Retrieving results

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 );

Updating results

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' ] );
}

Deleting results

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 );