Fluent Transition from Collections to Related Queries: toRelationQuery()

[serter35]

[Proposal] Fluent Transition from Collections to Related Queries: toRelationQuery()

High-Level Summary

Introducing toRelationQuery() for Eloquent Collections to allow a seamless, fluent transition from an existing collection of models to a Query Builder for their related models. This eliminates manual ID plucking and prevents breaking the "fluent chain" during bulk operations.

---

1. The Problem

Currently, performing bulk updates on related models requires leaving the collection context and manually bridging keys:

$comments = Comment::where('is_spam', true)->get();

// Manual bridging breaks the flow
Post::whereIn('id', $comments->pluck('post_id'))
    ->update(['has_spam_content' => true]);

2. The Solution

$comments->toRelationQuery('post')->update(['has_spam_content' => true]);

---

3. Why This Matters: Performance & Indexing

While Laravel provides whereHas() for querying relationships, it relies on EXISTS subqueries which can be suboptimal in certain scenarios:

• Query Optimizer Issues: In large datasets, database query optimizers (especially in MySQL) may fail to pick the correct index for EXISTS subqueries, leading to slow performance or full table scans.
• Predictable Execution: Transitioning from a collection to a whereIn query (which this method automates) provides a more predictable execution plan for the database engine.
• Encapsulation: The developer doesn't need to manually map foreign/owner keys. The relationship definition already holds this metadata.
• Fluent DX: Maintains readability and keeps the logic within the Eloquent chain.

---

4. Current Progress & POC

I have already implemented this as a macro. Here is the consolidated logic that handles both BelongsTo and HasOneOrMany relations:

/**
 * Create a query builder for the related models of the collection.
 */
public function toRelationQuery(string $relationName)
{
    $model = $this->first();

    if (! $model) {
        throw new \LogicException('Unable to create query for empty collection.');
    }

    $relation = $model->$relationName();

    return match (true) {
        // For HasOne/HasMany: Where foreign_key IN (collection_keys)
        $relation instanceof \Illuminate\Database\Eloquent\Relations\HasOneOrMany => 
            $relation->getRelated()->newQuery()->whereIn(
                $relation->getQualifiedForeignKeyName(),
                $this->modelKeys()
            ),

        // For BelongsTo: Where owner_key IN (collection_foreign_keys)
        $relation instanceof \Illuminate\Database\Eloquent\Relations\BelongsTo => 
            $relation->getRelated()->newQuery()->whereIn(
                $relation->getQualifiedOwnerKeyName(),
                $this->pluck($relation->getForeignKeyName())->filter()->unique()->values()->all()
            ),

        default => throw new \InvalidArgumentException("Unsupported relation type.")
    };
}

---

5. Common Real-World Scenarios

• Bulk Status Sync: $orders->toRelationQuery('customer')->update(['is_active' => true]);
• Mass Soft Deletes: $tags->toRelationQuery('posts')->delete();
• Conditional Updates: $shipmentUnits->toRelationQuery('item')->where('type', 'perishable')->update([...]);

I am ready to develop this into a production-ready Pull Request with full test coverage for the laravel/framework repository if the core team finds this proposal suitable.

[shaedrich]

While I like the overall idea, I think, mixing relation resolving logic with the Collection class is neither a good idea nor wanted. The problem with the currently existing implementation is

• the "loss" of context when doing model->collection
• the collection is not per se "typed"

I would propose to create a new typed collection that

• holds the model
• holds a query builder
• forwards calls to the query builder instance

[serter35]

That's a valid point regarding the separation of concerns, but I believe the "bridge" between Collections and Query Builders has already been established in Laravel core with the existing toQuery() method on the Eloquent Collection.

If toQuery() is allowed to resolve the models back into a builder, I see toRelationQuery() as a natural extension of that same philosophy. Instead of introducing a completely new "typed collection" structure—which might increase complexity—leveraging and extending the current behavior seems more in line with Laravel's "Developer Happiness" and consistency goals.

What do you think about following the precedent set by toQuery()?

[shaedrich]

Fair enough 👍🏻 I didn't have that on the radar ^^ In that case, this sounds like the reasonable step to take