Eloquent Power Joins

You can customize joins by passing a callback as the second argument to joinRelationship().

Basic Conditions

Use the $join instance to apply standard join conditions like where() or to change the join type:

User::joinRelationship('posts', fn ($join) => $join->where('posts.approved', true));

// Change join type inside callback
User::joinRelationship('posts', fn ($join) => $join->left());

Nested Callbacks

For nested relationships, pass an array where keys are the relationship names and values are the callbacks:

User::joinRelationship('posts.comments', [
    'posts' => fn ($join) => $join->where('posts.published', true),
    'comments' => fn ($join) => $join->where('comments.approved', true),
]);

Belongs To Many

For belongsToMany relationships, pass an array containing the relationship key and a nested array for the tables involved (the relationship table and the pivot table):

User::joinRelationship('groups', [
    'groups' => [
        'groups' => function ($join) {
            // ...
        },
        'group_members' => fn ($join) => $join->where('group_members.active', true),
    ]
]);

Eloquent Power Joins respects Laravel's model features like Soft Deletes and Global Scopes.

Soft Deletes

By default, if a joined model uses SoftDeletes, the package automatically adds deleted_at IS NULL to the join. To include trashed records, use withTrashed() or onlyTrashed() in the callback:

UserProfile::joinRelationship('users', fn ($join) => $join->withTrashed());
UserProfile::joinRelationship('users', fn ($join) => $join->onlyTrashed());

Global Scopes

To enable global scopes on a joined model, call withGlobalScopes() in the callback:

UserProfile::joinRelationship('users', fn ($join) => $join->withGlobalScopes());

Constraint: Your global scope cannot type-hint the Eloquent\Builder class in its apply method, or it will cause errors during joins.

Relationship Scopes

If your relationship definition in the Model includes a scope, it is automatically applied to the join:

// In User model
public function publishedPosts() {
    return $this->hasMany(Post::class)->published();
}

// Usage
User::joinRelationship('publishedPosts'); // Automatically applies 'published' scope

You can sort query results using columns from joined tables using the orderByPowerJoins family of methods.

Basic Ordering

User::orderByPowerJoins('profile.city');

// Using raw values
User::orderByPowerJoins(['profile', DB::raw('concat(city, ", ", state)')]);

Aggregate Ordering

Sort by counts, sums, averages, etc.:

• orderByPowerJoinsCount('relation.column', 'direction')
• orderByPowerJoinsSum('relation.column', 'direction')
• orderByPowerJoinsAvg('relation.column', 'direction')
• orderByPowerJoinsMin('relation.column', 'direction')
• orderByPowerJoinsMax('relation.column', 'direction')

Example: Sort users by highest number of posts:

$users = User::orderByPowerJoinsCount('posts.id', 'desc')->get();

Left Joins for Ordering

If you want to include records that have no related entries in the sort (using a LEFT JOIN), use the orderByLeft... prefix:

Post::orderByLeftPowerJoinsCount('comments.votes');

User::orderByPowerJoins('profile.city');

$users = User::orderByPowerJoinsCount('posts.id', 'desc')->get();

$posts = Post::orderByPowerJoinsAvg('comments.votes', 'desc')->get();

Post::orderByLeftPowerJoinsCount('comments.votes');

When joining the same table multiple times, you may need to use aliases. Use joinRelationshipUsingAlias() or the as() method within a callback.

Simple Aliasing

For non-nested joins, pass the alias as the second parameter:

Post::joinRelationshipUsingAlias('category', 'category_alias')->get();

Nested Aliasing

For nested joins, use the as() method within the callback array:

Post::joinRelationship('category.parent', [
    'category' => fn ($join) => $join->as('category_alias'),
    'parent' => fn ($join) => $join->as('category_parent'),
])->get();

Belongs To Many Aliasing

For many-to-many relationships, provide an array for the tables involved:

Group::joinRelationship('posts.user', [
    'posts' => [
        'posts' => fn ($join) => $join->as('posts_alias'),
        'post_groups' => fn ($join) => $join->as('post_groups_alias'),
    ],
])->toSql();

Standard Laravel has() and whereHas() methods use WHERE EXISTS subqueries. This package provides powerJoin alternatives that use joins instead, which can be more performant depending on your data structure.

Method Mapping

Using Callbacks with Many-to-Many/One-to-Many

When using powerJoinWhereHas on relationships involving multiple tables, use the array syntax to pass callbacks for the related tables:

User::powerJoinWhereHas('commentsThroughPosts', [
    'comments' => fn ($query) => $query->where('body', 'a')
])->get();

User::powerJoinHas('posts');
User::powerJoinHas('posts.comments', '>', 3);
User::powerJoinWhereHas('posts', function ($join) {
    $join->where('posts.published', true);
});
User::powerJoinDoesntHave('posts');