Eloquent Power Joins

https://github.com/kirschbaum-development/eloquent-power-joins
Admin
Eloquent Power Joins is a Laravel package that provides a more expressive and readable way to...
Tokens:66,104
Snippets:426
Trust Score:9.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/README.md

Install the eloquent-power-joins package using Composer. Laravel auto-discovers the service provider via the extra.laravel.providers entry in composer.json.

```bash
composer require kirschbaum-development/eloquent-power-joins
```

--------------------------------

### Usage example with joinRelationship and orderByPowerJoinsCount

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Shows typical usage after provider registration; no manual configuration needed.

```php
// app normal Laravel bootstrap — nothing to write
$users = User::query()
    ->joinRelationship('posts')
    ->orderByPowerJoinsCount('posts.id', 'desc')
    ->get();
```

--------------------------------

### Usage example with powerJoinHas

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Shows macros available after registration; uses powerJoinHas on Eloquent builder.

```php
$users = User::query()->powerJoinHas('posts')->get();
```

--------------------------------

### powerJoinHas() usage examples

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Shows two usage examples: a basic has('posts') check and a filtered version with a callback and count threshold. The first returns users with any posts; the second returns users with at least 3 published posts.

```php
User::query()->powerJoinHas('posts')->get();                            // has('posts')
User::query()->powerJoinHas('posts', '>=', 3, callback: fn ($j) => $j->published())->get();
```

--------------------------------

### orderByLeftPowerJoins() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Example call sorting by 'profile.city' using a left join.

```php
User::query()->orderByLeftPowerJoins('profile.city')->get();
```

--------------------------------

### Usage example (diagnostics)

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinsHelper.md

Shows how to inspect the cache key after joining a relationship. Note that a new model instance yields a fresh helper with an empty cache because the cache is keyed by object identity.

```php
// The cache key used after joining is kept on the model's helper.
// Useful while debugging why a join was skipped.
$users = User::query()->joinRelationship('posts');

$helper = JoinsHelper::make(new User);
var_dump($helper->relationshipAlreadyJoined(new User, 'posts.user_id_placeholder')); // false example
```

--------------------------------

### Usage example: powerJoinHas with nested relations

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Shows how to call the method via the powerJoinHas query builder method with a dotted relation path. The example queries users that have posts with comments, applying the default operator and count.

```php
User::query()->powerJoinHas('posts.comments')->get();
```

--------------------------------

### powerJoin() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Shows how to call powerJoin on an Eloquent builder to join the posts table. The example passes a table, first column, operator, second column, join type, where flag, and a Post model instance.

```php
User::query()->powerJoin('posts', 'posts.user_id', '=', 'users.id', 'inner', false, new Post)->get();
```

--------------------------------

### Usage example: getPowerJoinExistenceCompareKey() with HasMany

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Shows how to retrieve the existence compare key for a HasMany relationship, returning a qualified column string like 'posts.user_id'.

```php
$rel = User::query()->getModel()->posts();           // HasMany
// $rel->getPowerJoinExistenceCompareKey() === "posts.user_id" (qualified)
```

--------------------------------

### Usage examples: joinRelationship and powerJoinHas

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Demonstrates typical application patterns: joining a relation with extra conditions, disabling automatic replay, and using powerJoinHas with hasCheck for one-of-many relations.

```php
// A relation with an extra where condition is joined automatically:
// Post::coverImages() => morphMany(Image::class, 'imageable')->where('cover', true)
$posts = Post::query()->joinRelationship('coverImages')->get();
// -> join "images" on "images"."imageable_id" = "posts"."id"
//    and "images"."imageable_type" = ? and "images"."cover" = ?   (replayed by applyExtraConditions)

// Disable the automatic replay:
$posts = Post::query()
    ->joinRelationship('coverImages', disableExtraConditions: true)
    ->get();

// powerJoinHas always runs with hasCheck: true so one-of-many relations
// (->ofMany('votes', 'max')) are joined via an IN-subquery:
$posts = Post::query()->powerJoinHas('bestComment')->get();
```

--------------------------------

### leftPowerJoin() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Example of calling leftPowerJoin() on a query builder to perform a left join. The parameters mirror powerJoin() without $type and $where.

```php
User::query()->leftPowerJoin('posts', 'posts.user_id', '=', 'users.id')->get();
```

--------------------------------

### Usage example with aliased nested joins

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/StaticCache.md

Shows how StaticCache maps the Category model to 'category_alias' during a nested join, so the 'parent' join references 'category_alias'.parent_id.

```php
// The cache is keyed by object identity; the same effect is produced
// automatically when aliasing via callbacks:
Post::query()
    ->joinRelationship('category.parent', [
        'category' => fn ($join) => $join->as('category_alias'),
        'parent'   => fn ($join) => $join->as('parent_alias'),
    ])
    ->get();

// During the join, the 'parent' join references "category_alias"."parent_id"
// because StaticCache temporarily mapped the Category model to 'category_alias'.
```

--------------------------------

### on() usage with alias and conditions

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Usage of on() to add join conditions on an aliased table. The example aliases the 'user' relationship as 'u' and adds conditions on 'u.id' and 'u.active'.

```php
Post::query()
    ->joinRelationship('user', function ($join) {
        $join->as('u')
            ->on('u.id', '=', 'posts.user_id')
            ->on('u.active', '=', DB::raw('1'));
    })
    ->get();
```

--------------------------------

### as() with extra condition on aliased table

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Usage of as() combined with an additional where condition on the aliased table. The example aliases the 'profile' relationship as 'profile' and filters by 'profile.city' = 'Atlanta'.

```php
// alias + extra condition on the aliased table
User::query()
    ->joinRelationship('profile', function ($join) {
        $join->as('profile')->where('profile.city', 'Atlanta');
    })
    ->get();
```

--------------------------------

### getSelect() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryRelationshipExistence.md

Shows that getSelect() is null before execution unless a select() was called; the library registers a default 'users.*' via beforeQuery instead.

```php
$builder = User::query()->joinRelationship('posts');
// getSelect() is null before execution unless a select() was called;
// the library registers a default "users.*" via beforeQuery instead
```

--------------------------------

### usesSoftDeletes() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Shows how to call usesSoftDeletes() on a HasMany relation to a SoftDeletes model, passing the query's scopes array. The commented line indicates the expected boolean result.

```php
$relation = User::query()->getModel()->posts(); // HasMany to a SoftDeletes model
// $relation->usesSoftDeletes($relation->getQuery()->getScopes()) === true
```

--------------------------------

### getScopes() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryRelationshipExistence.md

Shows that after applying a scope, getScopes() exposes the relationship scopes internally.

```php
// after a scope was applied
$q = User::query()->where('active', true);
// $q->scopes contains the relationship scopes; getScopes() exposes them internally
```

--------------------------------

### where() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Returns self (fluent). Alias behavior: if $alias is set and the column already starts with "{$alias}.", it is passed through; if it contains $tableName, the "{$tableName}." prefix is replaced with "{$alias}."; otherwise a plain string column gets "{$alias}." prepended; callable columns are executed against a new self clause (nested where group). See also whereNull() at src/PowerJoinClause.php:181-188 which performs the same prefix replacement for alias-aware WHERE NULL clauses.

```php
public function where($column, $operator = null, $value = null, $boolean = 'and'): self
```

--------------------------------

### Usage example of FakeJoinCallback

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/FakeJoinCallback.md

Shows how FakeJoinCallback is used internally to probe a user callback and extract the alias. This is exactly what happens inside JoinsHelper::getAliasName() before a relationship is joined.

```php
use Kirschbaum\PowerJoins\FakeJoinCallback;

$probe = new FakeJoinCallback($parentQuery, 'inner', 'posts');
$callback($probe);          // user callback runs harmlessly
$alias = $probe->getAlias(); // e.g. 'post_alias'
```

```php
if (is_callable($callback)) {
    $fakeJoinCallback = new FakeJoinCallback($relation->getBaseQuery(), 'inner', $tableName);
    $callback($fakeJoinCallback);

    if ($fakeJoinCallback->getAlias()) {
        return $fakeJoinCallback->getAlias();
    }
}
```

--------------------------------

### clear() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinsHelper.md

Resets the joinRelationshipCache to a fresh WeakMap, forgetting every already-joined relationship for the helper's model. Invoked by the library's beforeQuery callback so each SQL execution starts with an empty cache.

```php
public function clear(): void
```

--------------------------------

### orderByPowerJoins() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Shows sorting by a nested relationship column with descending order. The array form uses DB::raw() to build a computed column expression.

```php
$users = User::query()->orderByPowerJoins('profile.city', 'desc')->get();
// array form: ['profile', DB::raw('CONCAT(user_profiles.city, \', \', user_profiles.state) as locale')]
```

--------------------------------

### getThroughParent() and getFarParent() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Demonstrates calling getThroughParent() and getFarParent() on a HasManyThrough relation. The comments show the expected return values: the Post model and the User model respectively.

```php
$rel = User::query()->getModel()->commentsThroughPosts(); // HasManyThrough
$rel->getThroughParent(); // Post model
$rel->getFarParent();     // User model
```

--------------------------------

### withTrashed() example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Removes the 'deleted_at is null' condition so soft-deleted rows of the joined model participate in the join. No-op when the clause has no model or the model does not use SoftDeletes.

```php
// include soft-deleted users in the join
$posts = Post::query()
    ->joinRelationship('user', function ($join) {
        $join->withTrashed();
    })
    ->get();
```

--------------------------------

### onlyTrashed() example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Keeps only soft-deleted rows of the joined model by adding a whereNotNull condition on the deleted-at column. No-op when the clause has no model or the model does not use SoftDeletes.

```php
// join only trashed users
$posts = Post::query()
    ->joinRelationship('user', function ($join) {
        $join->onlyTrashed();
    })
    ->get();
```

--------------------------------

### qualifyColumn() without alias

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Qualifies an unqualified column name with the table name when no alias is set. In this example, the column 'approved' becomes "comments"."approved".

```php
// without alias -> "comments"."approved"
Post::query()
    ->joinRelationship('comments', function (PowerJoinClause $join) {
        $join->where($join->qualifyColumn('approved'), true);
    })
    ->get();
```

--------------------------------

### getRelationWithoutConstraintsProxy() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryRelationshipExistence.md

Shows how powerJoinHas('posts') internally uses getRelationWithoutConstraintsProxy() to get the relation and then calls performJoinForEloquentPowerJoins().

```php
// internally, powerJoinHas('posts') does:
$relation = $this->getRelationWithoutConstraintsProxy('posts');
$relation->performJoinForEloquentPowerJoins($this, 'leftPowerJoin', $callback, morphable: $morphable, hasCheck: true);
```

--------------------------------

### boot() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Empty boot method; the provider publishes nothing and bootstraps nothing.

```php
public function boot()
{
}
```

--------------------------------

### powerJoinDoesntHave() exact signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Returns a Closure that calls powerJoinHas() with '<' and count 1 to emulate a 'doesnt have' relationship query. Example usage: User::query()->powerJoinDoesntHave('posts')->get().

```php
public function powerJoinDoesntHave(): Closure
{
    return function ($relation, $boolean = 'and', ?Closure $callback = null) {
        return $this->powerJoinHas($relation, '<', 1, $boolean, $callback);
    };
}
```

--------------------------------

### powerJoinWhereHas() exact signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Returns a Closure that calls powerJoinHas() with configurable operator and count, defaulting to '>=' and 1. Example usage: User::query()->powerJoinWhereHas('posts', fn ($j) => $j->published())->get().

```php
public function powerJoinWhereHas(): Closure
{
    return function ($relation, $callback = null, $operator = '>=', $count = 1) {
        return $this->powerJoinHas($relation, $operator, $count, 'and', $callback);
    };
}
```

--------------------------------

### Run tests

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/README.md

Command to run the package's test suite.

```bash
composer test
```

--------------------------------

### Package config file config/config.php

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/configuration.md

Ships with the package but returns an empty array. It is not loaded, merged, published, or read anywhere in the source; it is inert scaffolding.

```php
<?php

/*
 * You can place your custom package configuration in here.
 */
return [
];
```

--------------------------------

### Manual registration in config/app.php (Laravel < 11) - alternative

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Alternative manual registration for Laravel versions before 11.

```php
// Laravel < 11 — config/app.php
'providers' => [
    // ...
    \Kirschbaum\PowerJoins\PowerJoinsServiceProvider::class,
],
```

--------------------------------

### Power join methods for existence, ordering, and aggregation

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/README.md

Demonstrates three package methods: powerJoinHas for querying relationship existence, orderByPowerJoins for sorting by a related column, and orderByPowerJoinsCount for ordering by an aggregation on a related table.

```php
// Query relationship existence using joins instead of where exists
User::powerJoinHas('posts');

// Order by a related column
User::orderByPowerJoins('profile.city');

// Order by an aggregation on a related table
Post::orderByPowerJoinsCount('comments.id', 'desc');
```

--------------------------------

### Manual join query

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/README.md

Shows the traditional way of writing joins by hand in Laravel, which the package aims to replace.

```php
User::select('users.*')
    ->join('posts', 'posts.user_id', '=', 'users.id')
    ->join('comments', 'comments.post_id', '=', 'posts.id');
```

--------------------------------

### Import PowerJoinClause

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Import the PowerJoinClause class from the Kirschbaum\PowerJoins namespace.

```php
use Kirschbaum\PowerJoins\PowerJoinClause;
```

--------------------------------

### getGroupBy() usage example

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryRelationshipExistence.md

Shows how to call getGroupBy() on an Eloquent builder after applying powerJoinHas(). Returns null when no group by was set.

```php
$users = User::query()->powerJoinHas('posts');
var_dump(User::query()->getGroupBy()); // null when no group by was set
```

--------------------------------

### register() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Registers Eloquent macros by delegating to EloquentJoins::registerEloquentMacros().

```php
public function register()
{
    EloquentJoins::registerEloquentMacros();
}
```

--------------------------------

### Import StaticCache class

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/StaticCache.md

Import the StaticCache class for use in your PHP code.

```php
use Kirschbaum\PowerJoins\StaticCache;
```

--------------------------------

### Import EloquentJoins class

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/EloquentJoins.md

Import the EloquentJoins class from the Kirschbaum\PowerJoins namespace.

```php
use Kirschbaum\PowerJoins\EloquentJoins;
```

--------------------------------

### Manual registration when service provider is disabled

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/EloquentJoins.md

Use this when the service provider is disabled (e.g., in a package context or when auto-discovery is off). After calling registerEloquentMacros(), macros are available on every Eloquent builder in the process.

```php
use Kirschbaum\PowerJoins\EloquentJoins;

EloquentJoins::registerEloquentMacros();

// macros are now available on every Eloquent builder in this process
$users = User::query()->powerJoinHas('posts')->get();
```

--------------------------------

### on() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Signature for the on() method on PowerJoinClause. Accepts first column or closure, optional operator, second column/value, and boolean connector. Returns self for fluent chaining.

```php
public function on($first, $operator = null, $second = null, $boolean = 'and'): self
```

--------------------------------

### as()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Sets an alias for the joined table, rewriting the table name and conditions to use the alias. Returns the join clause instance for fluent chaining.

```APIDOC
## `as()`

### Description
Sets an alias for the joined table, rewriting the table name and conditions to use the alias. Returns the join clause instance for fluent chaining.

### Method
`as`

### Signature
```php
public function as(string $alias, ?string $joinedTableAlias = null): self
```

### Parameters
- `$alias` (string) - Required - Alias for the joined table. Rewrites `table` to `table as alias`.
- `$joinedTableAlias` (?string) - Optional - Optional second alias (used for BelongsToMany pivots).

### Returns
- `self` (fluent)

### Side Effects
- Stores `$alias`/`$joinedTableAlias`
- Sets `$this->table = "{$this->table} as {$alias}"`
- Rewrites existing ON/WHERE conditions to use the alias (`useTableAliasInConditions()`)
- When a model is attached, registers the alias in `StaticCache` via `StaticCache::setTableAliasForModel($this->model, $alias)` so subsequent joins reference the alias.

### Example
```php
// basic
Post::query()
    ->joinRelationship('category.parent', [
        'category' => fn ($join) => $join->as('category_alias'),
        'parent' => fn ($join) => $join->as('parent_alias'),
    ])
    ->get();
```

```php
// alias + extra condition on the aliased table
User::query()
    ->joinRelationship('profile', function ($join) {
        $join->as('profile')->where('profile.city', 'Atlanta');
    })
    ->get();
```
```

--------------------------------

### getRelationWithoutConstraintsProxy() macro signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryRelationshipExistence.md

Returns a relation instance instantiated under Relation::noConstraints(), so its query carries no parent-key constraints. Used by join builders to get the raw relationship definition.

```php
protected function getRelationWithoutConstraintsProxy()
{
    return function ($relation) {
        return Relation::noConstraints(function () use ($relation) {
            return $this->getModel()->{$relation}();
        });
    };
}
```

--------------------------------

### __call($name, $arguments)

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Magic method that provides fallback resolution for undefined methods. It resolves model scopes, Laravel Scope attributes, macros, custom Eloquent builder methods, or throws an exception.

```APIDOC
## __call($name, $arguments)

### Description
Magic method that provides fallback resolution for undefined methods. It resolves model scopes, Laravel Scope attributes, macros, custom Eloquent builder methods, or throws an exception.

### Method
__call()

### Parameters
- `$name` (string) - Required - The method name being called.
- `$arguments` (array) - Required - The arguments passed to the method.

### Returns
- Mixed - The result of the resolved method, or null if no model is set.

### Resolution Order
1. Model scope method (`scope{$name}`) on the joined model.
2. Laravel Scope attribute (`Illuminate\Database\Eloquent\Attributes\Scope`) when Laravel >= 12.0.0.
3. A macro registered on the clause.
4. The same method on `$this->getModel()->newEloquentBuilder($this)` (custom Eloquent builder).
5. Throws `InvalidArgumentException` if no method is found.

### Example
```php
$join->published(); // calls scopePublished on the joined model
```
```

--------------------------------

### withGlobalScopes() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Returns self (fluent). Applies the joined model's global scopes onto the join clause. Closure-backed scopes are called with $this (the clause) as builder; SoftDeletingScope instances are skipped (soft deletes are handled separately); other scope objects are instantiated and their apply($this, $this->model) invoked. No-op when $this->model is null.

```php
public function withGlobalScopes(): self
```

--------------------------------

### has-many-through with per-table aliases

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Example usage of joinNestedRelationship() for a has-many-through relationship with per-table aliases. The callback array maps each segment to nested callbacks for the pivot and related tables, using the as() method to alias the joined tables.

```php
// has-many-through with per-table aliases
User::query()
    ->joinNestedRelationship('commentsThroughPosts.user', [
        'commentsThroughPosts' => ['posts' => fn ($j) => $j->as('posts_alias'), 'comments' => fn ($j) => $j->as('comments_alias')],
    ])
    ->get();
```

--------------------------------

### getSelect() usage in joinRelationship()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryBuilderExtraMethods.md

Shows how power-join macros use getSelect() to decide whether they must inject a default "select \"mainTable\".*" before query execution. When getSelect() returns null, the library registers "users.*".

```php
// The power-join macros use getSelect() to decide whether they must
// inject a default "select \"mainTable\".*" before query execution.
$builder = User::query()->joinRelationship('posts');
// $builder->getQuery()->getSelect() === null  -> library registers "users.*"
```

--------------------------------

### performJoinForEloquentPowerJoins() dispatcher signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Macro closure that dispatches to per-relation join builders based on the relation type. Accepts join type, callback, alias, and flags for extra conditions, morphable class, and has-check. Returns the relation for fluency.

```php
public function performJoinForEloquentPowerJoins()
{
    return function ($builder, $joinType = 'leftJoin', $callback = null, $alias = null, bool $disableExtraConditions = false, ?string $morphable = null, bool $hasCheck = false) {
        return match (true) {
            $this instanceof MorphToMany => $this->performJoinForEloquentPowerJoinsForMorphToMany($builder, $joinType, $callback, $alias, $disableExtraConditions),
            $this instanceof BelongsToMany => $this->performJoinForEloquentPowerJoinsForBelongsToMany($builder, $joinType, $callback, $alias, $disableExtraConditions),
            $this instanceof MorphOneOrMany => $this->performJoinForEloquentPowerJoinsForMorph($builder, $joinType, $callback, $alias, $disableExtraConditions),
            $this instanceof HasMany || $this instanceof HasOne => $this->performJoinForEloquentPowerJoinsForHasMany($builder, $joinType, $callback, $alias, $disableExtraConditions, $hasCheck),
            $this instanceof HasManyThrough || $this instanceof HasOneThrough => $this->performJoinForEloquentPowerJoinsForHasManyThrough($builder, $joinType, $callback, $alias, $disableExtraConditions),
            $this instanceof MorphTo => $this->performJoinForEloquentPowerJoinsForMorphTo($builder, $joinType, $callback, $alias, $disableExtraConditions, $morphable),
            default => $this->performJoinForEloquentPowerJoinsForBelongsTo($builder, $joinType, $callback, $alias, $disableExtraConditions),
        };
    };
}
```

--------------------------------

### Join-type switcher methods

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Declares the fluent methods to switch the join type: left(), right(), inner(), and joinType(). Each returns self and sets the clause's type property.

```php
public function left(): self     // -> $this->joinType('left')
public function right(): self    // -> $this->joinType('right')
public function inner(): self    // -> $this->joinType('inner')
public function joinType(string $joinType): self
```

--------------------------------

### newQuery()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Creates a new PowerJoinClause instance for the same parent query, type, and table, carrying the model forward. This is used internally when nested where closures spawn sub-clauses.

```APIDOC
## newQuery()

### Description
Creates a new PowerJoinClause instance for the same parent query, type, and table, carrying the model forward. This is used internally when nested where closures spawn sub-clauses.

### Method
newQuery()

### Parameters
None

### Returns
- `self` - A new PowerJoinClause instance.

### Example
```php
$newClause = $join->newQuery();
```
```

--------------------------------

### Calling a custom Eloquent builder method from join callback

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Shows how to call a method of a custom Eloquent builder (PostBuilder::whereReviewed) from within a join callback. The method is resolved via the __call() magic method.

```php
// calling a method of a custom Eloquent builder (PostBuilder::whereReviewed)
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->whereReviewed();
    })
    ->get();
```

--------------------------------

### newQuery() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Declares the newQuery() method that returns a new PowerJoinClause for the same parent query/type/table, carrying the model forward. Used internally when nested where closures spawn sub-clauses.

```php
public function newQuery(): self
```

--------------------------------

### Import PowerJoinsServiceProvider

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Import the service provider class for use in Laravel configuration or code.

```php
use Kirschbaum\PowerJoins\PowerJoinsServiceProvider;
```

--------------------------------

### withGlobalScopes()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Applies the joined model's global scopes to the join clause. Closure-backed scopes are called with the clause as builder; SoftDeletingScope instances are skipped; other scope objects are instantiated and applied. No-op when the model is null.

```APIDOC
## withGlobalScopes()

### Description
Applies the joined model's global scopes onto the join clause. Closure-backed scopes are called with the clause as builder; `SoftDeletingScope` instances are skipped; other scope objects are instantiated and their `apply` method invoked. No-op when the model is null.

### Method
`withGlobalScopes()`

### Returns
- `self` - Fluent return for chaining.

### Behavior
- Applies global scopes from the joined model.
- Closure-backed scopes are called with `$this` (the clause) as builder.
- `SoftDeletingScope` instances are skipped (soft deletes handled separately).
- Other scope objects are instantiated and their `apply($this, $this->model)` invoked.
- No-op when `$this->model` is `null`.

### Example
```php
// PostWithGlobalScope hides unpublished posts through a global scope
$users = User::query()
    ->joinRelationship('posts', fn ($join) => $join->withGlobalScopes())
    ->get();

// -> SQL: inner join "posts" on "posts"."user_id" = "users"."id" and "posts"."published" = ?
```

```php
// combine with soft-delete awareness: withGlobalScopes() never removes the
// soft-delete condition itself; use withTrashed() to drop it
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->withGlobalScopes()->withTrashed();
    })
    ->get();
```

```

--------------------------------

### Register Eloquent Power Joins Macros

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/README.md

Registers all Power Joins macros on Laravel query builders and relations. Called by the service provider during registration; no manual configuration or trait import is needed.

```php
public static function registerEloquentMacros()
{
    EloquentQueryBuilder::mixin(new JoinRelationship());
    EloquentQueryBuilder::mixin(new QueryRelationshipExistence());
    QueryBuilder::mixin(new QueryBuilderExtraMethods());

    Relation::mixin(new RelationshipsExtraMethods());
}
```

--------------------------------

### applyExtraConditions() method

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Replays the relationship query's where conditions onto the join clause, skipping FK-comparison conditions via shouldNotApplyExtraCondition(). Returns a closure that accepts a PowerJoinClause and returns void.

```php
public function applyExtraConditions()
{
    return function (PowerJoinClause $join) {
        foreach ($this->getQuery()->getQuery()->wheres as $condition) {
            if ($this->shouldNotApplyExtraCondition($condition)) {
                continue;
            }

            if (!in_array($condition['type'], ['Basic', 'Null', 'NotNull', 'Nested'], true)) {
                continue;
            }

            $method = "apply{$condition['type']}Condition";
            $this->$method($join, $condition);
        }
    };
}
```

--------------------------------

### Direct usage on raw query builder

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryBuilderExtraMethods.md

Because the mixin targets Illuminate\Database\Query\Builder, the accessors also exist on raw query builders from DB::table()/DB::query(). Demonstrates getSelect() returning null before select() is called, then the explicit columns after; getGroupBy() returns the groupBy columns.

```php
use Illuminate\Support\Facades\DB;

$query = DB::table('users');
var_dump($query->getSelect());   // null (no explicit select)
$query->select('id', 'name');
var_dump($query->getSelect());   // ['id', 'name']

$query->groupBy('users.id');
var_dump($query->getGroupBy());  // ['users.id']
```

--------------------------------

### applyBasicCondition(), applyNullCondition(), applyNotNullCondition(), applyNestedCondition() methods

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Four closures that apply specific where condition types to the join clause. Each returns void and is dispatched dynamically by applyExtraConditions().

```php
public function applyBasicCondition()
{
    return function ($join, $condition) {
        $join->where($condition['column'], $condition['operator'], $condition['value'], $condition['boolean']);
    };
}
```

```php
public function applyNullCondition()
{
    return function ($join, $condition) {
        $join->whereNull($condition['column'], $condition['boolean']);
    };
}
```

```php
public function applyNotNullCondition()
{
    return function ($join, $condition) {
        $join->whereNotNull($condition['column'], $condition['boolean']);
    };
}
```

```php
public function applyNestedCondition()
{
    return function ($join, $condition) {
        $join->where(function ($q) use ($condition) {
            foreach ($condition['query']->wheres as $condition) {
                $method = "apply{$condition['type']}Condition";
                $this->$method($q, $condition);
            }
        });
    };
}
```

--------------------------------

### where() basic usage

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Basic usage — column auto-qualified to the joined table/alias.

```php
// basic — column auto-qualified to the joined table/alias
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->where('posts.published', true);
    })
    ->get();
```

--------------------------------

### __call() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Declares the magic fallback method __call(). It resolves method calls in a specific order: model scope, Laravel Scope attribute, macro, custom Eloquent builder, or throws an exception. Returns immediately if getModel() is null.

```php
public function __call($name, $arguments)
```

--------------------------------

### Composer auto-discovery configuration

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Laravel auto-discovers the provider via the extra.laravel.providers entry in composer.json.

```json
"extra": {
    "laravel": {
        "providers": [
            "Kirschbaum\\PowerJoins\\PowerJoinsServiceProvider"
        ]
    }
}
```

--------------------------------

### as() basic usage with joinRelationship

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Basic usage of as() to alias joined tables in a joinRelationship call. Applies aliases 'category_alias' and 'parent_alias' to the 'category' and 'parent' relationships respectively.

```php
// basic
Post::query()
    ->joinRelationship('category.parent', [
        'category' => fn ($join) => $join->as('category_alias'),
        'parent' => fn ($join) => $join->as('parent_alias'),
    ])
    ->get();
```

--------------------------------

### as() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Signature for the as() method on PowerJoinClause. Accepts an alias and an optional joined table alias for BelongsToMany pivots, returns self for fluent chaining.

```php
public function as(string $alias, ?string $joinedTableAlias = null): self
```

--------------------------------

### getGroupBy() usage in powerJoinHas()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/QueryBuilderExtraMethods.md

Shows how the library internally checks getGroupBy() when building SQL for powerJoinHas(). The accessor returns null when no GROUP BY columns were set.

```php
$sql = User::query()->powerJoinHas('posts')->toSql(); // internally checks getGroupBy()
```

--------------------------------

### usesSoftDeletes() macro implementation

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Defines the usesSoftDeletes() macro. Accepts a Model instance or an array of scopes (from getScopes()); returns true if the model uses the SoftDeletes trait or the scope array contains SoftDeletingScope::class.

```php
public function usesSoftDeletes()
{
    /*
     * @param \Illuminate\Database\Eloquent\Model|array $model
     */
    return function ($model) {
        if ($model instanceof Model) {
            return in_array(SoftDeletes::class, class_uses_recursive($model), true);
        }

        return array_key_exists(SoftDeletingScope::class, $model);
    };
}
```

--------------------------------

### on()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Adds an ON condition to the join clause, delegating to the parent JoinClause::on() and then rewriting conditions to use the alias if set. Returns the join clause instance for fluent chaining.

```APIDOC
## `on()`

### Description
Adds an ON condition to the join clause, delegating to the parent JoinClause::on() and then rewriting conditions to use the alias if set. Returns the join clause instance for fluent chaining.

### Method
`on`

### Signature
```php
public function on($first, $operator = null, $second = null, $boolean = 'and'): self
```

### Parameters
- `$first` (mixed) - Required - First column (or closure for a nested `ON` group).
- `$operator` (mixed) - Optional - Comparison operator.
- `$second` (mixed) - Optional - Second column/value.
- `$boolean` (string) - Optional - Boolean connector (`'and'` / `'or'`). Default: `'and'`.

### Returns
- `self` (fluent)

### Behavior
- Delegates to the parent `JoinClause::on()` then rewrites conditions to the alias if set.

### Example
```php
Post::query()
    ->joinRelationship('user', function ($join) {
        $join->as('u')
            ->on('u.id', '=', 'posts.user_id')
            ->on('u.active', '=', DB::raw('1'));
    })
    ->get();
```
```

--------------------------------

### Equivalent joinRelationship, leftJoinRelationship, and performJoinForEloquentPowerJoins calls

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Shows the automatic dispatch of join methods on a HasMany relationship. joinRelationship uses a power join ('join'), leftJoinRelationship uses 'leftJoin', and performJoinForEloquentPowerJoins is called with 'leftPowerJoin' on the relationship instance.

```php
// dispatched automatically — these are equivalent:
User::query()->joinRelationship('posts');                       // uses powerJoin ('join')
User::query()->leftJoinRelationship('posts');                   // 'leftJoin'
$relation = User::query()->getModel()->posts();                 // HasMany instance
$relation->performJoinForEloquentPowerJoins(User::query(), 'leftPowerJoin');
```

--------------------------------

### Calling a model scope from join callback

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Shows how to call a model scope (published()) on the joined model from within a join callback. The scope is resolved via the __call() magic method.

```php
// calling a model scope from the join callback
// published() is a scope on the Post model
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->published();
    })
    ->get();
```

--------------------------------

### orderByPowerJoinsMin and orderByLeftPowerJoinsMin macros

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinRelationship.md

Defines two macros that hard-code the 'MIN' aggregation. Both return a Closure that calls orderByPowerJoins with the given sort and direction, optionally using 'leftJoin'. The left variant uses joinType 'leftJoin'.

```php
public function orderByPowerJoinsMin(): Closure
{
    return function (string|array $sort, string $direction = 'asc') {
        return $this->orderByPowerJoins(sort: $sort, direction: $direction, aggregation: 'MIN');
    };
}

public function orderByLeftPowerJoinsMin(): Closure
{
    return function (string|array $sort, string $direction = 'asc') {
        return $this->orderByPowerJoins(sort: $sort, direction: $direction, aggregation: 'MIN', joinType: 'leftJoin');
    };
}
```

--------------------------------

### getPowerJoinExistenceCompareKey() method

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/RelationshipsExtraMethods.md

Returns a closure that provides the qualified column name(s) identifying the relationship's foreign key constraint, varying by relation type. Returns a single string for BelongsTo/Has*/BelongsToMany and arrays for Morph relations.

```php
public function getPowerJoinExistenceCompareKey()
{
    return function () {
        if ($this instanceof MorphTo) {
            return [$this->getMorphType(), $this->getForeignKeyName()];
        }

        if ($this instanceof BelongsTo) {
            return $this->getQualifiedOwnerKeyName();
        }

        if ($this instanceof HasMany || $this instanceof HasOne) {
            return $this->getExistenceCompareKey();
        }

        if ($this instanceof HasManyThrough || $this instanceof HasOneThrough) {
            return $this->getQualifiedFirstKeyName();
        }

        if ($this instanceof BelongsToMany) {
            return $this->getExistenceCompareKey();
        }

        if ($this instanceof MorphOneOrMany) {
            return [$this->getQualifiedMorphType(), $this->getExistenceCompareKey()];
        }
    };
}
```

--------------------------------

### Manual registration in config/app.php (Laravel < 11)

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Register the provider manually when auto-discovery is disabled or not used.

```php
// config/app.php (Laravel < 11) or bootstrap/providers.php (Laravel 11+)
'providers' => [
    // ...
    \Kirschbaum\PowerJoins\PowerJoinsServiceProvider::class,
],
```

--------------------------------

### Using left() inside a join callback

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Shows how to select the final join type inside a callback passed to joinRelationship(). The left() method switches the join to a left join.

```php
// inside a callback you can still pick the final join type
Comment::query()
    ->joinRelationship('post', function ($join) {
        $join->left();
    })
    ->get();
```

--------------------------------

### Import FakeJoinCallback class

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/FakeJoinCallback.md

Import the FakeJoinCallback class from the Kirschbaum\PowerJoins namespace.

```php
use Kirschbaum\PowerJoins\FakeJoinCallback;
```

--------------------------------

### markRelationshipAsAlreadyJoined() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinsHelper.md

Records the relationship in the per-model WeakMap cache so later joinRelationship() calls on the same object skip the duplicate join. Returns void.

```php
public function markRelationshipAsAlreadyJoined($model, string $relation): void
```

--------------------------------

### Error handling for unknown scope method

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Error handling for unknown scope method inside a join callback. Throws InvalidArgumentException with message "Method typoScope does not exist in PowerJoinClause class".

```php
// error handling for unknown scope method inside a join callback
use InvalidArgumentException;

try {
    User::query()
        ->joinRelationship('posts', fn ($join) => $join->typoScope());
} catch (InvalidArgumentException $e) {
    // "Method typoScope does not exist in PowerJoinClause class"
}
```

--------------------------------

### PowerJoinClause constructor signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

The constructor signature for PowerJoinClause. It accepts the parent query builder, join type, table name, and optionally the joined model.

```php
public function __construct(Builder $parentQuery, $type, string $table, ?Model $model = null)
```

--------------------------------

### relationshipAlreadyJoined() method signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/JoinsHelper.md

Checks if a relationship was already joined on this helper's cache. Returns true when the relationship is already joined.

```php
public function relationshipAlreadyJoined($model, string $relation): bool
```

--------------------------------

### qualifyColumn() with alias

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Qualifies a column with the alias when one is set. Here, the alias 'c' is used, so 'approved' becomes "c"."approved" and 'created_at' becomes "c"."created_at".

```php
// with alias -> "c"."approved"
Post::query()
    ->joinRelationship('comments', function (PowerJoinClause $join) {
        $join->as('c')
            ->where($join->qualifyColumn('approved'), true)
            ->whereColumn($join->qualifyColumn('created_at'), '>=', 'posts.created_at');
    })
    ->get();
```

--------------------------------

### Join type mapping via $joinMethodsMap

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/types.md

Maps join type strings to power join methods. Unrecognized strings are used as-is, allowing direct use of 'powerJoin', 'leftPowerJoin', or 'rightPowerJoin'.

```php
public static $joinMethodsMap = [
    'join' => 'powerJoin',
    'leftJoin' => 'leftPowerJoin',
    'rightJoin' => 'rightPowerJoin',
];
```

--------------------------------

### Basic usage with auto-registration

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/EloquentJoins.md

When the service provider is auto-registered, no manual registration is needed. The comment shows that PowerJoinsServiceProvider::register() calls EloquentJoins::registerEloquentMacros() automatically.

```php
// No code needed. PowerJoinsServiceProvider::register()
// calls EloquentJoins::registerEloquentMacros() automatically.
$users = User::query()->joinRelationship('posts')->get();
```

--------------------------------

### withGlobalScopes() combined with withTrashed()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Combine with soft-delete awareness: withGlobalScopes() never removes the soft-delete condition itself; use withTrashed() to drop it.

```php
// combine with soft-delete awareness: withGlobalScopes() never removes the
// soft-delete condition itself; use withTrashed() to drop it
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->withGlobalScopes()->withTrashed();
    })
    ->get();
```

--------------------------------

### clear() signature

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/StaticCache.md

Empties the static cache.

```php
public static function clear(): void
```

--------------------------------

### Manual registration in bootstrap/providers.php (Laravel 11+)

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinsServiceProvider.md

Register the provider manually in Laravel 11+ when auto-discovery is disabled.

```php
// Laravel 11+ — bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    \Kirschbaum\PowerJoins\PowerJoinsServiceProvider::class,
];
```

--------------------------------

### where()

Source: https://github.com/kirschbaum-development/eloquent-power-joins/blob/master/_autodocs/api-reference/PowerJoinClause.md

Adds a where condition to the join clause, with alias-aware column qualification. Supports callable columns for nested where groups.

```APIDOC
## where()

### Description
Adds a where condition to the join clause. The column is automatically qualified with the joined table or alias if an alias is set. Supports callable columns for nested where groups.

### Method
`where($column, $operator = null, $value = null, $boolean = 'and')`

### Parameters
- `$column` (mixed) - Required - Column name or callable. If the clause has an alias, the column is prefixed/rewritten to the alias.
- `$operator` (mixed) - Optional - Comparison operator. Default: `null`.
- `$value` (mixed) - Optional - Value. Default: `null`.
- `$boolean` (string) - Optional - Connector. Default: `'and'`.

### Returns
- `self` - Fluent return for chaining.

### Alias Behavior
- If `$alias` is set and the column already starts with `"{$alias}."`, it is passed through.
- If it contains `$tableName`, the `"{$tableName}."` prefix is replaced with `"{$alias}."`.
- Otherwise a plain string column gets `"{$alias}."` prepended.
- Callable columns are executed against a new `self` clause (nested where group).

### Example
```php
// basic — column auto-qualified to the joined table/alias
User::query()
    ->joinRelationship('posts', function ($join) {
        $join->where('posts.published', true);
    })
    ->get();
```

### Error Handling
```php
// error handling for unknown scope method inside a join callback
use InvalidArgumentException;

try {
    User::query()
        ->joinRelationship('posts', fn ($join) => $join->typoScope());
} catch (InvalidArgumentException $e) {
    // "Method typoScope does not exist in PowerJoinClause class"
}
```

```
Tokens:
Raw