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

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:

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:

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.

After models, continue with: