Proposed update to Laravel relationships

[inxilpro]

Context

I would like to propose an overhaul of the underlying implementation of the Laravel Relation classes (HasMany, BelongsTo, etc). To understand the reasoning, it's important to understand how relationships are queried in Laravel.

Querying Relationships (as it exists today)

Right now, Laravel queries relationships three different ways depending on whether you're loading a relationship directly, loading it eagerly using with(), or querying its existence using something like has().

Expand summary of existing implementation

Non-Eager Mode

In the simplest terms, this is may look something like:

select *
from `related`
where `parent_id` = /* ID of parent */

• A Relation object is instantiated and addConstraints() is called. The object needs to check whether Relation::$constraints has been set to determine if we're loading the relation or using the object for eager loading or an aggregate function. If the flag is true, the relation should add any necessary constraints to the query builder.
• getResults() is called on the relation to get the results, which are then passed to Model::setRelation to be applied to the model.

Eager Mode

In the simplest terms, this is may look something like:

select *
from `related`
where `parent_id` IN (/* list of parent IDs */)

• A static Relation::$constraints flag is set to false, and then a Relation object is instantiated and addConstraints() is called. Because Relation::$constraints has been set to false, addConstraints is expected to do nothing.
• addEagerConstraints is called, which needs to set up the query builder for eager loading.
• getEager() is called on the relation to get the eager results, which are then passed to match() so that the results can be matched back to the parents.

Aggregate Mode

This is when you're calling something like whereHas() that's not actually returning the relation models, but checking existence or counting them. It may look something like:

select *
from `parent`
where exists(
  select *
  from `related`
  where `related`.`parent_id` = `parent`.`id`
)

• Like in eager mode, the Relation object is instantiated with Relation::$constraints set to false so that the default constraints are not applied (this is done via a getRelationWithoutConstraints() method on the Eloquent builder).
• Depending on whether we're checking for existence or comparing the count, either getRelationExistenceQuery or getRelationExistenceCountQuery is called. This is a performance optimization, because checking existence can be faster than getting the actual count.
• The query from the getRelationExistence* call is then added to the parent query as a subquery and constraints are merged into the parent query.

Inserting & Updating Related Models

There are lots of helper functions like save() and create() that are responsible for setting the correct keys on the correct models while saving them. These methods are outside of the scope of this suggested change.

The Idea

Once you wrap your head around Laravel relationships, there are two things that I believe stand out:

1. The logic around Relation::$constraints can be confusing and I imagine is the result of backwards-compatible changes over time.
2. The differences between eager and non-eager contexts is arguably unnecessary.

In the end, I think querying a relationship can be thought of in the following way:

• Given n number of parent models, apply constraints to the query builder
• Match those results back to the parents

In a non-eager context, a naive relation could be implemented as:

select *
from `related`
where `parent_id` IN(/* ID of single parent */)

Whereas a more sophisticated relation could add some logic branching that looked a little bit like:

if (count($parents) === 1) {
  // Use "where `parent_id` = ID"
} else {
  // Use "where `parent_id` IN(list of parent IDs)"
}

By thinking in "eager mode" by default, we can simplify the Relation interface, and essentially make "non-eager mode" a performance optimization.

The same can be done for aggregate mode. We can use "count" queries by default, and allow relations to define an alternate "existence" query as a performance optimization if needed.

In the end, the relevant parts of the interface would look like:

interface Relation
{
  // Apply constraints to the query builder. $parents can be one or many
  // parents, so assume eager loading by default and optimize for non-eager
  // queries only if necessary.
  function addConstraints(Builder $query, Collection $parents): void;
  
  // Match a given result back to 0, 1, or many $parents.
  function matchResult(Model $result, Collection $parents): array;
  
  // Get the aggregate subquery to be used in `whereHas`-style contexts
  function getCountSubQuery(Builder $query, Builder $parentQuery): Builder;
}

Realistically, it would have to be a little more complex than this, but I'm trying to stick to the bare minimum for the purpose of example. One thing I'm leaving out for simplicity's sake is the difference between "to one" and "to many" relationships, which complicates things a little but doesn't change the underlying concepts.

Backwards Compatibility

In the end, I think the Relation classes could be rewritten without causing any backwards compatibility issues for folks who use the methods defined in HasRelationships like $this->hasMany()/etc. The interface for instantiating a new relationship would not change at all.

This would be a major breaking change for anyone who has implemented a custom relationship using the existing abstract Relation class. As such, it would have to be introduced in the 9.x release at the earliest.

(I also think that a separate class could be provided, either within the framework or in a compatibility package, that would implement the new interface using the old Relation class methods, so that the initial upgrade path could be to replace extends Relation with extends BackwardsCompatibleRelation.)

Summary

In the end, I think this could improve the existing code base and provide a much easier starting point for anyone who wants to implement custom relationships in their own projects.

I already have some work done on this idea, but I don't want to undergo a real pull request against the framework without some buy-in from maintainers (obviously the devil is in the details so I don't expect buy-in here to guarantee a merge in the framework—I just don't want to submit a PR that will never even get considered).

Let me know what y'all think!

[DanielCoulbourne]

Just wanted to weigh in that I've been working with some mentoring clients lately on custom relationships and it DOES seem that addConstraints, addEagerConstraints, match system is a bit hard to wrap your head around at first. We spent three one-hour sessions implementing a custom relationship for complex Jetstream permissions for which we already had a working query builder. Most of that time was spent trying make sure we were doing the correct work in the correct place. Creating a single path for relationships could make the process of getting started with custom relationships much simpler.