> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/core-concepts/models.md).

# Models

## Overview

Models in Quantum PHP Framework provide a structured way to represent and manipulate application data. They encapsulate data attributes, business rules, and database interactions in a clear and reusable class.

Quantum provides a layered model system starting from a base `Model` class and extending to `DbModel` for database-backed entities.

***

## Base Model Class

* Manages attributes with support for fillable and hidden properties.
* Allows safe filling of data and conversion to arrays with hidden property filtering.
* Implements magic getters/setters for attribute access.
* Checks for empty models via attribute presence.

***

## DbModel Class

* Extends the base Model to integrate with an ORM instance (e.g., Idiorm, SleekDB).
* Adds querying capabilities including filters, joins, pagination, sorting, and grouping.
* Handles database record fetching, creation, updating, saving, and deletion.
* Supports wrapping ORM results as model instances.
* Syncs model attributes with ORM properties for persistence.
* Throws domain-specific exceptions for ORM or model errors.

***

## Usage Pattern

```php
namespace Modules\YourModule\Models;

use Quantum\Model\DbModel;

class YourModel extends DbModel
{
    public string $table = 'your_table_name';

    public string $idColumn = 'id';

    public array $fillable = [
        'name',
        'email',
        // other columns
    ];

    public array $hidden = [
        'password',
        // sensitive fields
    ];

    // Define relationships and custom methods here
}
```

***

## How to Use Models

Typically, models are accessed and manipulated through service classes using the `model()` helper function.

Inside a service:

```php
public function __construct()
{
    $this->model = model(YourModel::class);
}

public function getAll()
{
    return $this->model->get();
}

public function findById(string $id)
{
    return $this->model->findOneBy('id', $id);
}
```

Services encapsulate business logic and data operations, and controllers or other app components call these services.

***

## Model Relationships

Quantum models define relationships to other models using the `relations()` method.

This method returns an array mapping related model classes to configuration arrays specifying:

* `type`: Relation type (e.g., `Relation::BELONGS_TO`, `Relation::HAS_MANY`, `Relation::HAS_ONE`)
* `foreign_key`: The foreign key column in the related model
* `local_key`: The local key column in the current model

### Relationship Types

* `Relation::BELONGS_TO`: This model belongs to the related model (many-to-one).
* `Relation::HAS_MANY`: This model has many related models (one-to-many).
* `Relation::HAS_ONE`: This model has a single related model (one-to-one).

### Example:

```php
public function relations(): array
{
    return [
        User::class => [
            'type' => Relation::BELONGS_TO,
            'foreign_key' => 'user_uuid',
            'local_key' => 'uuid',
        ]
    ];
}
```

This definition allows the framework to understand and resolve model associations for queries and data access.

***

## Benefits of Using Models

* Centralize data representation and logic.
* Facilitate database interaction and query building.
* Promote secure attribute handling.
* Enable conversion between ORM results and application objects.
* Support clean and testable domain logic.

***

## What to read next

After models, continue with:

* [Services](/docs/core-concepts/services.md)
* [Database](/docs/advanced-features/database.md)
* [Migration](/docs/advanced-features/migration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/core-concepts/models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.