Active Record Pattern
debt(d7/e7/b8/t5)
Closest to 'only careful code review or runtime testing' (d7). While phpstan and phpcs are listed as detection tools, the detection_hints note automated=no — the real problem (business logic creeping into models, wrong architectural choice for a complex domain) cannot be caught automatically. The code_pattern describes Eloquent models with business logic methods sending emails/making HTTP calls, which requires careful code review to identify as a misuse. A static analysis rule could flag model size or certain method patterns, but the architectural mismatch is fundamentally a review-time judgment.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix says 'use service classes or domain objects for logic, and models only for persistence,' but once Active Record models have become God Objects with 50+ methods, extracting business logic into services/domain objects touches every controller, job, command, and test that calls those model methods. This is a cross-cutting refactor. Moving from Active Record to Repository/Data Mapper when the domain has outgrown it is even harder, approaching architectural rework (e9). Scoring e7 as the typical remediation case.
Closest to 'defines the system's shape' (b9), adjusted down to b8. Active Record is a foundational architectural pattern that applies across all contexts (web, cli, queue-worker per applies_to). It shapes how every piece of the application interacts with data — models are referenced everywhere, relationships define the data graph, query scopes define how data is accessed. It has strong gravitational pull (b7) and arguably defines the system's shape (b9). Scoring b8 because while it's deeply load-bearing, frameworks like Laravel do provide escape hatches (raw queries, query builder) so it doesn't completely lock you in.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field states developers wrongly believe 'Active Record is always an anti-pattern,' when it's actually appropriate for simple CRUD. The inverse trap — using it for complex domains — is equally common. Common_mistakes list N+1 queries from lazy loading, God Objects from business logic in models, and difficulty unit testing without a database. These are well-documented gotchas that most developers eventually learn but routinely fall into initially. Not t7 because Active Record behaves as advertised; the trap is about scope/boundary of appropriate use rather than contradicting expectations.
Also Known As
TL;DR
Explanation
Active Record (Martin Fowler, PoEAA) places persistence logic inside the domain object: User::find(1), $user->save(), $user->delete(). The object maps directly to a database row. Advantages: simple, low boilerplate, excellent for CRUD applications. Disadvantages: couples domain logic to persistence, makes unit testing without a database hard, violates SRP, and becomes unwieldy for complex domain logic. Laravel's Eloquent, Ruby on Rails, Django ORM are all Active Record implementations.
Common Misconception
Why It Matters
Common Mistakes
- Business logic inside Active Record models — they become unmaintainable God Objects.
- Unit testing Active Record models without a database — requires database setup, making tests slow.
- N+1 queries from lazy loading — always eager-load relationships with with() in Eloquent.
- Using Active Record when a complex aggregate requires multiple tables — use Repository instead.
Avoid When
- Domain logic is complex — mixing business rules with persistence makes both harder to test and change.
- You need to support multiple storage backends or swap databases; the object is tightly coupled to one schema.
- Writing unit tests that should not touch a database — the persistence coupling forces slow integration tests.
When To Use
- Simple CRUD-heavy apps where domain logic is thin and co-locating persistence with data is acceptable.
- Rapid prototyping or internal tools where the overhead of a separate data mapper is not justified.
- Teams already using a framework (Laravel Eloquent, Rails) where Active Record is the idiomatic default.
Code Examples
// Active Record model doing too much:
class Order extends Model {
public function process(): void {
// Validation, pricing, inventory, emails all in one class
if ($this->total > $this->customer->credit_limit) throw new Exception();
$this->status = 'processing';
$this->save();
$this->inventory->decrement($this->items);
Mail::send(new OrderConfirmation($this));
// Untestable without DB, email service, inventory service
}
}// Active Record for simple CRUD — appropriate:
class User extends Model {
protected $fillable = ['name', 'email'];
protected $hidden = ['password'];
public function orders(): HasMany {
return $this->hasMany(Order::class);
}
}
// Simple — maps rows to objects, relationships via ORM
// Complex domain logic extracted to dedicated service classes