belongs-to-through

Install the package using Composer. For standard environments, use the first command. If you are using PowerShell on Windows (e.g., within VS Code), use the second command to avoid issues with character escaping.

composer require staudenmeir/belongs-to-through:"^2.5"

# For PowerShell on Windows:
composer require staudenmeir/belongs-to-through:"^^^^2.5"

If a relationship path includes the same model multiple times, you can use table aliases (Laravel 6+). To do this, pass the model name with an alias string (e.g., Model::class . ' as alias') as an intermediate model.

Crucially, you must also use the \Znck\Eloquent\Traits\HasTableAlias trait in the models that are being aliased.

class Comment extends Model
{
    use \Znck\Eloquent\Traits\HasTableAlias;

    public function grandparent(): \Znck\Eloquent\Relations\BelongsToThrough
    {
        return $this->belongsToThrough(
            Comment::class,
            Comment::class . ' as alias',
            foreignKeyLookup: [Comment::class => 'parent_id']
        );
    }
}

The BelongsToThrough relationship allows an Eloquent model to belong to a related model through one or more intermediate "through" models. This is useful for traversing deep relationship chains (e.g., User -> Post -> Category where User belongs to Category through Post).

Key features include:

• Multi-level traversal: Supports an arbitrary number of intermediate models.
• Soft Delete support: Automatically handles SoftDeletes on intermediate models by applying global scopes to ensure only non-deleted through-parents are joined.
• Custom Key Mapping: Allows overriding default foreign and local key lookups for the intermediate models.
• Eager Loading: Fully supports Eloquent's eager loading mechanism.

To ensure that belongs-to-through relationships are correctly recognized by IDE autocomplete and static analysis tools, the package automatically registers a hook with barryvdh/laravel-ide-helper.

This is handled via the IdeHelperServiceProvider, which injects Staudenmeir\BelongsToThrough\IdeHelper\BelongsToThroughRelationsHook into the ide-helper.model_hooks configuration array. No manual configuration is required if you have laravel-ide-helper installed in your Laravel project.

To specify custom local keys for the relations, use the localKeyLookup option. This takes an associative array where the keys are the intermediate model classes and the values are the local key names.

class CustomerAddress extends Model
{
    use \Znck\Eloquent\Traits\BelongsToThrough;

    public function vendorCustomer(): \Znck\Eloquent\Relations\BelongsToThrough
    {
        return $this->belongsToThrough(
            VendorCustomer::class,
            VendorCustomerAddress::class,
            foreignKeyLookup: [VendorCustomerAddress::class => 'id'],
            localKeyLookup: [VendorCustomerAddress::class => 'address_id'],
        );
    }
}

If your intermediate models use non-standard foreign keys, you can specify them using the foreignKeyLookup option. This option takes an associative array where the keys are the intermediate model classes and the values are the custom foreign key names.

class Comment extends Model
{
    use \Znck\Eloquent\Traits\BelongsToThrough;

    public function country(): \Znck\Eloquent\Relations\BelongsToThrough
    {
        return $this->belongsToThrough(
            Country::class,
            [User::class, Post::class], 
            foreignKeyLookup: [User::class => 'custom_user_id']
        );
    }
}

By default, BelongsToThrough excludes soft-deleted intermediate models from the results. To include them, use the withTrashed() method on the relationship, passing the column name used for soft deletes (e.g., 'users.deleted_at').

class Comment extends Model
{
    use \Znck\Eloquent\Traits\BelongsToThrough;

    public function country(): \Znck\Eloquent\Relations\BelongsToThrough
    {
        return $this->belongsToThrough(Country::class, [User::class, Post::class])
            ->withTrashed('users.deleted_at');
    }
}

When the default naming convention (singular table name + _id) does not match your database schema, you can provide custom mappings for foreign keys and local keys for the intermediate models.

These mappings are passed to the BelongsToThrough constructor via $foreignKeyLookup and $localKeyLookup arrays, where the keys are the table names and the values are the specific column names.