> 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/packages/model/overview.md).

# Overview

The Model package gives Quantum two data shapes:

* `Quantum\Model\Model` for plain in-memory objects with guarded mass assignment
* `Quantum\Model\DbModel` for database-backed records that query through the active DBAL adapter

Use `Model` when you want a small data object with `fillable` and `hidden` rules. Use `DbModel` when the class should also load, query, save, paginate, or delete database records.

## Typical model shape

```php
namespace Modules\Blog\Models;

use Quantum\Database\Enums\Relation;
use Quantum\Model\DbModel;
use Quantum\Model\Traits\HasTimestamps;
use Quantum\Model\Traits\SoftDeletes;

class Post extends DbModel
{
    use HasTimestamps;
    use SoftDeletes;

    public string $table = 'posts';

    public array $fillable = [
        'title',
        'slug',
        'body',
        'author_id',
    ];

    public array $hidden = [
        'deleted_at',
    ];

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

## What the package manages

At runtime, the package is responsible for:

* building model instances with `model()` or `ModelFactory`
* attaching the active database adapter to `DbModel` classes
* wrapping DBAL results back into model objects
* exposing collection results through `ModelCollection`
* adding optional timestamp and soft-delete behavior through traits

## Entry points

### `model(Foo::class)`

Use `model()` when you want a normal model class instance.

For plain `Model` subclasses, it returns a new object.

For `DbModel` subclasses, it also creates and attaches the ORM/DBAL instance for the current configured database driver.

### `dynamicModel(...)`

Use `dynamicModel()` when you need a lightweight anonymous `DbModel` for table-level work without creating a named class.

This is useful for one-off internal queries, admin tooling, or package code that needs a table wrapper but not a full domain model class.

### `wrapToModel(...)`

This helper is used internally when query results need to come back as model objects. It returns `null` for missing records and otherwise hydrates a new `DbModel` instance from the DBAL row.

## Important package rules

* `fill()` only accepts keys listed in `$fillable`.
* Direct property assignment like `$post->title = '...'` bypasses `$fillable` checks.
* `asArray()` hides keys listed in `$hidden`, but the raw properties still exist on the model.
* `DbModel::save()` skips writing the primary key field back into the ORM payload and then syncs the generated key from the ORM after save.
* Query methods mutate the current `DbModel` instance. Reuse the same instance only when you want to keep building on the same query state.
* The package supports relation definitions, but join behavior only works for relation types the DBAL adapters implement today: `hasOne`, `hasMany`, and `belongsTo`.
* `belongsToMany` exists in the `Relation` enum but is not handled by `joinTo()`.


---

# 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/packages/model/overview.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.