Models
In HivePress, models are PHP classes used as wrappers for WordPress post types, comment types and taxonomies. With models, you can easily create, retrieve, update and delete any database entries in the same way without worrying about data validation and storage.
Let's take a look at the main operations you can perform on models. 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 creates a new listing in the database, then the listing is marked as featured, and finally, the listing is deleted.
// Create listing.
$listing = ( new HivePress\Models\Listing() )->fill(
[
'title' => 'Custom title',
'description' => 'Custom text',
]
);
if ( $listing->save( [ 'title', 'description' ] ) ) {
// Mark as featured.
$listing->set_featured( true )->save_featured();
// Delete listing.
$listing->delete();
}
To create a model object, create a new instance of the
HivePress\Models\{Model_Name}
class and call the fill
method with an array of field values. You can check the available fields in the model class file or invoke the _get_fields
method that returns an array of field objects. The model object will not be saved in the database until you call the save
method:// Create listing.
$listing = ( new HivePress\Models\Listing() )->fill(
[
'title' => 'Custom title',
'featured' => true,
]
);
// Save listing.
$listing->save();
If the object is not saved (e.g. some required fields are empty), you can check the value returned by
save
(instead of calling it separately) and get an array of validation errors:if ( ! $listing->save() ) {
$errors = $listing->_get_errors();
}
After the object is saved in the database, it gets a unique ID:
$id = $listing->get_id();
To retrieve a model object from the database, simply query it by ID. Please refer to the Making Queries page if you want to retrieve multiple objects at once.
$listing = HivePress\Models\Listing::query()->get_by_id( 123 );
if ( $listing ) {
// Listing exists.
}
After you retrieve an object, you can get any field value by calling the
get_{field_name}
method:$title = $listing->get_title();
Also, you can use
has_{field_name}
and is_{field_name}
aliases for better code readability:if ( $listing->has_title() && $listing->is_featured() ) {
// Do something.
}
To get the formatted field value, use the
display_{field_name}
method instead:echo $listing->display_description();
If a field references another model object, you can access its field values via the double underscore:
$name = $listing->get_vendor__name();
To get an array of all the field values, use the
serialize
method:$values = $listing->serialize();
Call the
set_{field_name}
method to set the field value:$listing->set_title( 'Custom title' );
If a field references another model object, you can use its ID as a value:
$listing->set_vendor( 123 );
To set multiple fields at once, call the
fill
method with an array of values:$listing->fill(
[
'title' => 'Custom title',
'featured' => true,
]
);
There are a few ways to save changes in the database. You can call the
save
method without arguments to save all fields, pass an array of field names to save, or save a single field by calling the save_{field_name}
method:// Save all fields.
$listing->save();
// Save specific fields.
$listing->save( [ 'title', 'featured' ] );
// Save a single field.
$listing->save_title();
Also, you can chain methods for better code readability:
$listing->set_title( 'example' )->save_title();
To delete a model object from the database, call the
delete
method:$listing->delete();
Check the method result if you want to make sure that the object is deleted:
if ( ! $listing->delete() ) {
// Listing can't be deleted.
}
Also, models that inherit the
Post
or Comment
classes can be moved to Trash:$listing->trash();
Last modified 1yr ago