How should we be using Models & Records?

[Mosnar]

This has been a repeated topic of discussion over the years; however, I wanted to bring it up again to try to make sure it's clear; because based on the conversations I've recently had, there's still a lot of confusion.

The docs from Craft 2 say we should only be using ActiveRecords in our services, but I couldn't find updated docs for Craft 3 on this topic. Based on how things are currently structured, it seems like this is the idiomatic approach (based on how a Site is saved):

• Controllers are responsible for hydrating Models from user submitted data
• Controllers ask a relevant service if a row exists in the database for a given ID. The service should use a MemoizableArray of data that has already been fetched using the QueryBuilder, (not ActiveRecord)
• Controllers invoke a "save" method on a relevant service, providing a hydrated Model
• The relevant service invokes the validation method on the model, which has the rules defined on it
• If the data is stored in ProjectConfig - trigger the update via ->set() on the project config service, passing along an associative array of data.
• An associative array of presumably validated data is passed to another method in the service to convert the data to a proper ActiveRecord - each of the ActiveRecord attributes is set individually. No additional validation occurs.
• The record is saved via ->save(false)
• The saved record's new ID and UID may be set back on the original model.

Based on this, these are the assumptions I would make:

• We shouldn't be using ActiveRecord for querying data, only saving data
• We shouldn't use validation in our Records, but instead keep validation in our models
• We shouldn't be using ActiveRecord's relationships or eager-loading, as these result in more Records that would need to be converted to models
• We should always define a Model AND a Record for something that will be saved to the database.
• Records should always be hydrated property-by-property rather than filling

So my question is, are these assumptions correct, and if so, how could I more easily explain this reasoning and why it makes sense to a new developer extending Craft?

[khalwat]

I recall having a conversation with @brandonkelly about this some time ago; the details are fuzzy, but I believe they went with using :: createCommand() to create a db command to read the data in, and then create models from it... and only used ActiveRecord for saving... all for performance reasons.

I'm assuming they did the performance timings on ActiveRecord, and using it throughout resulted in worse performance than the aforementioned pattern.

[samhernandez]

It's difficult to make it short, isn't it? I'm trying to find ways to simplify these concepts too because Craft is new to my organization and we might be using it more.

The docs provide a bunch of this info already, but here's how I have it organized in my head. Please let me know if I misunderstand anything.

---

Given that "model" implies "Element"...

Elements are models and a lot more

Elements have validation rules and scenarios, so they are the model, just with a ton of functionality around custom fields, and more.

Element Queries

Example: Entry::find() returns and EntryQuery; base is ElementQuery. An ElementQuery class defines the element table name at the very least.

Element Queries come with custom field chaining, assume you only want enabled status (use ->anyStatus() otherwise), do some caching, and more stuff you never want to have to worry about. :) To save an element to the database, you want to use Craft::$app->getElements()->saveElement() because there are often side effects that need to happen.

ActiveRecord

If you just need to write something quick to the database, use ActiveRecord. It's relatively slow, but writes don't happen often (hopefully) and you end up with really clean, readable code which is another kind of optimization.

You'll find it in the afterSave() method of Element classes where they write data to their own table after the elements table has been populated.

You don't have to use ActiveRecord, it's just quick to write and easy to read.

Query Builder

If you don't need the overhead of either of those, then a Query instance is handy.

An example from Craft's own code:

$this->groupId = (new Query())
    ->select(['id'])
    ->from([Table::USERGROUPS])
    ->where(Db::parseParam('handle', $value))
     ->column();

It's not a huge leap from ActiveRecord and you'll find places in Craft core where it's used for quick writes and reads in place of ActiveRecord. The Yii Query Builder docs are very helpful.

DB Commands

Craft::$app->getDb()->createCommand() returns a Command which is a low-level db class. It lets you manipulate tables, do soft deletes, and things like that. Most importantly for what we're talking about here, it lets you run raw SQL.

// with great power...
Craft::$app->getDb()->createCommand('delete * from elements')->execute();

[brandonkelly]

There’s nothing inherently wrong with using ActiveRecord, and it’s not something I feel super strongly about one way or the other. But we have avoided it for a few reasons:

• They come with a memory & performance hit, compared to using normal DB queries and populating a model with predefined properties. Not as bad in Craft 3 thanks to schema caching and better code, but still a factor.
• There is a 1:1 mapping of record attributes and DB table columns, which isn’t always ideal. Some models (particularly elements) have properties whose data span across multiple DB tables. Even in cases where the 1:1 mapping is fine, you might want to work with it in a different format than its stored (e.g. a DateTime object vs. a timestamp; an array vs. JSON).
• They aren’t really compatible with Craft’s service/repository architecture, where the services are expected to be the source of truth. If it’s common practice to fetch a section record and save it directly, then we could no longer trust Craft::$app->sections->getAllSections() to return accurate results.

We shouldn't be using ActiveRecord for querying data, only saving data

If you want to follow our lead, then yes. Saving data is basically the only reason we keep Craft’s own AR classes around, as they still provide a little value there (e.g. tracking changed values) and are more elegant than manually constructing an insert/update/delete command with the query builder.

We shouldn't use validation in our Records, but instead keep validation in our models

Correct. No reason to validate twice, and validation should always happen as early as possible, before we’ve committed to saving something to the database. That’s particularly important for things getting stored to the Project Config, where the PC data has already been updated by the time the DB gets written to.

We shouldn't be using ActiveRecord's relationships or eager-loading, as these result in more Records that would need to be converted to models

If performance could benefit from AR eager-loading, it might be worth considering. Craft doesn’t offer any better solutions, besides for elements.

We should always define a Model AND a Record for something that will be saved to the database.

Probably, given AR’s caveats.

Records should always be hydrated property-by-property rather than filling

No opinion here. If something like $record->setAttributes($model->getAttributes()) works for you, go for it.

So my question is, are these assumptions correct, and if so, how could I more easily explain this reasoning and why it makes sense to a new developer extending Craft?

Great question. It seems to me like part of the solution might be that we need to become a bit more dogmatic: avoid AR entirely in Craft’s own code, and come up with a better solution for keeping models, the database, and the project config data in sync. Unlikely that we’ll have time to address that in time for 4.0, but maybe after that ships. In the meantime, we are open to ideas on how the docs could be improved.