# 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.

### Quick example <a href="#bkmrk-quick-example" id="bkmrk-quick-example"></a>

The code example below creates a new listing in the database, then the listing is marked as featured, and finally, the listing is deleted.

```php
// 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();
}
```

### Creating objects <a href="#bkmrk-creating-objects" id="bkmrk-creating-objects"></a>

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:

```php
// 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:

```php
if ( ! $listing->save() ) {
	$errors = $listing->_get_errors();
}
```

After the object is saved in the database, it gets a unique ID:

```php
$id = $listing->get_id();
```

### Retrieving objects <a href="#bkmrk-retrieving-objects" id="bkmrk-retrieving-objects"></a>

To retrieve a model object from the database, simply query it by ID. Please refer to the [Making Queries](/developer-docs/framework/models/making-queries.md) page if you want to retrieve multiple objects at once.

```php
$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:

```php
$title = $listing->get_title();
```

Also, you can use `has_{field_name}` and `is_{field_name}` aliases for better code readability:

```php
if ( $listing->has_title() && $listing->is_featured() ) {
	// Do something.
}
```

To get the formatted field value, use the `display_{field_name}` method instead:

```php
echo $listing->display_description();
```

If a field references another model object, you can access its field values via the double underscore:

```php
$name = $listing->get_vendor__name();
```

To get an array of all the field values, use the `serialize` method:

```php
$values = $listing->serialize();
```

### Updating objects <a href="#bkmrk-updating-objects" id="bkmrk-updating-objects"></a>

Call the `set_{field_name}` method to set the field value:

```php
$listing->set_title( 'Custom title' );
```

If a field references another model object, you can use its ID as a value:

```php
$listing->set_vendor( 123 );
```

To set multiple fields at once, call the `fill` method with an array of values:

```php
$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:

```php
// 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:

```php
$listing->set_title( 'example' )->save_title();
```

### Deleting objects <a href="#bkmrk-deleting-objects" id="bkmrk-deleting-objects"></a>

To delete a model object from the database, call the `delete` method:

```php
$listing->delete();
```

Check the method result if you want to make sure that the object is deleted:

```php
if ( ! $listing->delete() ) {
	// Listing can't be deleted.
}
```

Also, models that inherit the `Post` or `Comment` classes can be moved to **Trash**:

```php
$listing->trash();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hivepress.io/developer-docs/framework/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.