Models, Resource Models & Collections

There are four types of classes related to loading and storing data in Magento:

1. Models - Store data (one row)
2. Resource Models - Database operations (save/load/delete)
3. Collections - Load multiple models
4. Repositories - API wrapper for data operations

What are Models?

Models are classes with getters and setters to store data. An instantiated class would represent one row in the database.

Example:

This model is initialized with a reference to the Resource Model.

<?php
namespace Vendor\Module\Model;

use Magento\Framework\Model\AbstractModel;

class CustomEntity extends AbstractModel
{
    protected function _construct()
    {
        $this->_init(\Vendor\Module\Model\ResourceModel\CustomEntity::class);
    }
}

Models that extend \Magento\Framework\Model\AbstractModel will thus extend \Magento\Framework\DataObject. This means that the data is stored in the class' $_data property.

You can convert snake-case notation to camel-case notation and use magic methods:

// Column name: discount_amount
// Magic getter
$discountAmount = $model->getDiscountAmount();

// Magic setter
$model->setDiscountAmount(100);

// OR use getData/setData
$discountAmount = $model->getData('discount_amount');
$model->setData('discount_amount', 100);

Instead of magic getters/setters, it's recommended to build out explicit methods:

public function getDiscountAmount(): float
{
    return (float)$this->getData('discount_amount');
}

public function setDiscountAmount(float $discountAmount): void
{
    $this->setData('discount_amount', $discountAmount);
}

Advantages:

• ✅ Type hints - reduces unnecessary conversions (float to int, etc.)
• ✅ Mockable - can mock these methods in unit tests
• ✅ Custom handling - can customize how data is handled (e.g., json_encode in setter)

What are Resource Models?

Resource models are classes responsible for saving and loading data. They handle direct database operations.

Example:

These classes almost always inherit \Magento\Framework\Model\ResourceModel\Db\AbstractDb.

Primary Methods:

• load() - Load data into model
• save() - Save model data to database
• delete() - Delete model data from database

Resource models are initialized with:

• The table name (as found in db_schema.xml)
• The name of the primary key column

<?php
namespace Vendor\Module\Model\ResourceModel;

use Magento\Framework\Model\ResourceModel\Db\AbstractDb;

class CustomEntity extends AbstractDb
{
    protected function _construct()
    {
        $this->_init('vendor_module_custom_entity', 'entity_id');
        //       table name                        primary key
    }
}

The resource model is the place to put any custom selects (using the Magento ORM, and NOT writing direct SQL).

Example: Get Count with Custom Query

public function getAvailableToTranslate(string $language): int
{
    $select = $this->getConnection()->select();
    $select->from($this->getMainTable(), 'COUNT(id)');
    $select->where('needs_translation = ?', true);
    $select->where('language = ?', $language);
    
    return (int)$this->getConnection()->fetchOne($select);
}

Various fetch methods available for different result types:

What are Collections?

Collections load multiple models. They handle loading multiple rows for a database entity or table.

Example:

This class is initialized with a reference to the Model and Resource Model.

<?php
namespace Vendor\Module\Model\ResourceModel\CustomEntity;

use Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection;

class Collection extends AbstractCollection
{
    protected function _construct()
    {
        $this->_init(
            \Vendor\Module\Model\CustomEntity::class,
            \Vendor\Module\Model\ResourceModel\CustomEntity::class
        );
    }
}

// DON'T inject the collection directly
// DO inject the CollectionFactory

public function __construct(
    \Magento\Cms\Model\ResourceModel\Page\CollectionFactory $collectionFactory
) {
    $this->collectionFactory = $collectionFactory;
}

public function getPages()
{
    $collection = $this->collectionFactory->create(); // Instantiate fresh
    return $collection;
}

Because collections implement the \IteratorAggregate interface, you can loop through a collection in a foreach() method.

$collection = $this->collectionFactory->create();
$collection->addFieldToFilter('status', 1);

foreach ($collection as $item) {
    echo $item->getName();
}

1. addFieldToFilter()

This is the equivalent of adding a WHERE clause to a SQL select.

$collection->addFieldToFilter('product_id', ['neq' => $productId]);
// SQL: SELECT * FROM table_name WHERE product_id <> 4;

Common Conditionals:

• ['eq' => $value] - Equal to
• ['neq' => $value] - Not equal to
• ['gt' => $value] - Greater than
• ['gteq' => $value] - Greater than or equal
• ['lt' => $value] - Less than
• ['lteq' => $value] - Less than or equal
• ['like' => '%value%'] - LIKE pattern
• ['in' => [$val1, $val2]] - IN array
• ['nin' => [$val1, $val2]] - NOT IN array
• ['null' => true] - IS NULL
• ['notnull' => true] - IS NOT NULL

2. addAttributeToFilter()

On EAV entities (Magento\Eav\Model\Entity\Collection\AbstractCollection): this is the same as addFieldToFilter() for EAV-enabled entities. If you call either method, you get the same result.

// For EAV entities (products, categories, customers)
$collection->addAttributeToFilter('status', 1);

3. join()

Joins in another table.

$collection->join(
    ['table_alias' => 'table_name'],
    'main_table.product_id = table_alias.product_id',
    ['column_a']
);

// Results in:
// SELECT *, table_alias.column_a 
// FROM original_table AS main_table
// INNER JOIN table_name AS table_alias 
//     ON main_entity.product_id = table_alias.product_id;

4. load()

This fetches the results of the collection. Data is loaded from the database and then models are hydrated with said data.

$collection->load(); // Executes the query and loads data

5. getSize()

This creates a copy of the select, strips out the columns, and uses the COUNT method.

$count = $collection->getSize(); // Returns count of items

What are Repositories?

Repositories handle the primary actions that happen to a database table. They are often a wrapper for the Resource Model.

Repositories usually have:

• save() - Save a model
• getById() - Get one row/model from the database
• getList() - Accepts a SearchCriteria class, returns multiple items
• delete() - Delete a model

Repositories do not inherit another class. They represent more of an idea (unlike models, resource models, or collections).

Common Injected Classes:

• Model's Factory
• Resource Model
• Collection Factory
• SearchResults Factory

Example:

<?php
namespace Vendor\Module\Model;

use Vendor\Module\Api\CustomEntityRepositoryInterface;
use Vendor\Module\Model\CustomEntityFactory;
use Vendor\Module\Model\ResourceModel\CustomEntity as ResourceModel;

class CustomEntityRepository implements CustomEntityRepositoryInterface
{
    private $entityFactory;
    private $resourceModel;
    
    public function __construct(
        CustomEntityFactory $entityFactory,
        ResourceModel $resourceModel
    ) {
        $this->entityFactory = $entityFactory;
        $this->resourceModel = $resourceModel;
    }
    
    public function getById(int $id)
    {
        $entity = $this->entityFactory->create();
        $this->resourceModel->load($entity, $id);
        
        if (!$entity->getId()) {
            throw new NoSuchEntityException(__('Entity not found'));
        }
        
        return $entity;
    }
    
    public function save($entity)
    {
        $this->resourceModel->save($entity);
        return $entity;
    }
    
    public function delete($entity)
    {
        $this->resourceModel->delete($entity);
        return true;
    }
}

Repositories are often a wrapper for the Resource Model. The latter has no way to instantiate a model: the repository creates the model (via the model's factory) and then passes it to the Resource Model's load() method.

Repositories are commonly an API Endpoint (the service class in a webapi.xml file).

For this situation, you would:

1. Create an interface that the repository then implements
2. Declare the route and resources required in webapi.xml

How do they differ?

For a normal model (like a CMS page or an order), there would be no difference.

Originally, a repository was designed for use through an API: APIs are less concerned about speed and more about how much information can be returned.

• A collection loads a list of models
• A resource model directly interacts with the database
• A resource model handles loading (hydrating) a model class that is already instantiated
• A model stores data - get() and set() are used frequently
• A repository creates models and uses resource models to load/save data
• Collections implement \IteratorAggregate so you can use foreach()

• Models
• Repositories
• Code Generation (Factories)