Belongs To Through Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require staudenmeir/belongs-to-through

Verify compatibility with your Laravel version (e.g., ^2.18 for Laravel 13.x).

2. First Use Case: Define a BelongsToThrough relationship in a model where a parent model indirectly owns a child model via one or more intermediate models. Example: A User belongs to a Team through UserTeam and TeamMembership:

   // User.php
   use Staudenmeir\LaravelBelongsToThrough\HasBelongsToThrough;
   
   class User extends Model
   {
       use HasBelongsToThrough;
   
       public function team()
       {
           return $this->belongsToThrough(
               Team::class,          // Target model
               UserTeam::class,      // First intermediate model
               'user_id',            // Foreign key on first intermediate
               'team_id',            // Foreign key on first intermediate
               'id',                 // Owner key on first intermediate
               TeamMembership::class, // Second intermediate model
               'user_team_id',       // Foreign key on second intermediate
               'team_id',            // Foreign key on second intermediate
               'id'                  // Owner key on second intermediate
           );
       }
   }
   

3. First Query:

   $user = User::find(1);
   $team = $user->team; // Eagerly loads the team via intermediates
   

Implementation Patterns

Core Workflows

1. Basic Relationships:

   • Use belongsToThrough() for single-step or multi-step indirect relationships.
   • Define foreign keys and owner keys for each intermediate model in the chain.
   • Example for a 3-level relationship:

     return $this->belongsToThrough(
         Target::class,
         Intermediate1::class, 'fk1', 'fk2', 'owner_key1',
         Intermediate2::class, 'fk3', 'fk4', 'owner_key2',
         Intermediate3::class, 'fk5', 'fk6', 'owner_key3'
     );
     

2. Eager Loading:

   • Use with() to optimize queries:

     $users = User::with('team')->get();
     

   • Supports nested eager loading (Laravel 8.43+):

     $users = User::with('team.members')->get();
     

3. Custom Constraints:

   • Add where() clauses to filter intermediate models:

     $user->team()->where('active', true);
     

   • Use whereHas() for deeper constraints:

     $user->team()->whereHas('memberships', fn($q) => $q->where('role', 'admin'));
     

4. Polymorphic Relationships:

   • Combine with polymorphic keys for flexible ownership:

     return $this->belongsToThrough(
         Target::class,
         Intermediate::class,
         'owner_id', 'owner_type', 'intermediate_id'
     );
     

5. Dynamic Relationships:

   • Use when() to conditionally define relationships:

     public function optionalTeam()
     {
         return $this->when($this->isPremium(), function() {
             return $this->belongsToThrough(Team::class, UserTeam::class, ...);
         });
     }
     

Integration Tips

• API Resources:
  • Transform relationships in API responses:

    public function toArray($request)
    {
        return [
            'team' => TeamResource::make($this->whenLoaded('team')),
        ];
    }
    

• Form Requests:
  • Validate intermediate model data before saving:

    public function rules()
    {
        return [
            'team_id' => 'required|exists:teams,id',
            'membership_data' => 'sometimes|array',
        ];
    }
    

• Observers/Events:
  • Trigger events when intermediates are updated:

    UserTeam::observe(UserTeamObserver::class);
    
    // UserTeamObserver.php
    public function saved(UserTeam $userTeam)
    {
        $userTeam->user->team->refresh();
    }
    

Gotchas and Tips

Common Pitfalls

1. Key Mismatches:

   • Ensure foreign keys and owner keys match the database schema exactly.
   • Debug with dd($this->team->getQuery()->toSql()) to verify generated queries.

2. Missing Intermediate Models:

   • If an intermediate model in the chain doesn’t exist, the relationship returns null.
   • Add exists() checks:

     if ($user->team()->exists()) { ... }
     

3. N+1 Queries:

   • Always eager load relationships in collections:

     // Bad: N+1 queries
     foreach ($users as $user) {
         $user->team; // Triggers a query per user
     }
     
     // Good: Single query
     $users->load('team');
     

4. Circular References:

   • Avoid bidirectional relationships that create infinite loops (e.g., User->Team->User).
   • Use withDefault() to break cycles:

     return $this->belongsToThrough(...)->withDefault();
     

5. Soft Deletes:

   • Intermediate models must implement SoftDeletes for proper soft-delete handling:

     use Illuminate\Database\Eloquent\SoftDeletes;
     
     class UserTeam extends Model
     {
         use SoftDeletes;
     }
     

Debugging Tips

• Query Logging: Enable Laravel’s query logging to inspect generated SQL:

  DB::enableQueryLog();
  $user->team;
  dd(DB::getQueryLog());
  

• Relationship Dumping: Use toBase() to inspect the relationship structure:

  dd($this->team->getRelationship()->toBase());
  

• Constraint Debugging: For complex whereHas clauses, test intermediate queries separately:

  $query = $this->team()->whereHas('memberships', fn($q) => $q->where('role', 'admin'));
  dd($query->toSql());
  

Extension Points

1. Custom Accessors:
   • Add computed properties to relationships:

     public function getTeamNameAttribute()
     {
         return $this->team?->name ?? 'No Team';
     }
     

2. Macros:
   • Extend the relationship with custom logic:

     BelongsToThrough::macro('withRole', function($role) {
         return $this->whereHas('memberships', fn($q) => $q->where('role', $role));
     });
     
     // Usage:
     $user->team->withRole('admin');
     

3. Scopes:
   • Create reusable scopes for relationships:

     class TeamScope
     {
         public function scopeActive($query)
         {
             return $query->whereHas('memberships', fn($q) => $q->where('active', true));
         }
     }
     
     // Usage:
     $user->team()->active();
     

4. Custom Intermediate Logic:
   • Override intermediate model behavior via events or observers:

     TeamMembership::observe(function($model) {
         if ($model->wasRecentlyCreated) {
             $model->user->team->refresh();
         }
     });
     

Configuration Quirks

• Laravel Version Compatibility:
  • Package versions align with Laravel major versions (e.g., ^2.18 for Laravel 13.x).
  • Downgrade the package if upgrading Laravel breaks functionality.
• Caching:
  • Relationship results are cached per query. Clear caches when intermediate data changes:

    $user->team->refresh();
    

• Database Transactions:
  • Ensure intermediate models are saved within a transaction to maintain consistency:

    DB::transaction(function() {
        $userTeam = $user->userTeams()->create([...]);
        $membership = $userTeam->memberships()->create([...]);
    });
    

```markdown
### Pro Tips for Daily Use
1. **Partial Loading**:
   Use `with()` to load only specific attributes of the target model:
   ```php
   $user->load('team:id,name'); // Loads only id and name

2. Relationship Metadata: Access metadata like exists or wasRecentlyCreated:

   if ($user->team->exists) {
       $user->team->touch(); // Update last accessed timestamp
   }
   

3. Dynamic Intermediate Chains: Build relationships dynamically based on runtime conditions:

   $intermediates = $this->getIntermediateModels();
   $this->buildThroughRelationship($intermediates);
   

4. Performance Profiling: Use Laravel Debugbar to compare query counts before/after implementing belongsToThrough.

5. Testing: Mock relationships in tests:

   $user = User::factory()->create();
   $team = Team::