staudenmeir / eloquent-has-many-deep
Laravel Eloquent HasManyThrough relationships with unlimited levels
Fund package maintenance!
paypal.me/JonasStaudenmeir
Installs: 7 996 862
Dependents: 42
Suggesters: 0
Security: 0
Stars: 2 686
Watchers: 44
Forks: 158
Open Issues: 0
Requires
- php: ^8.2
- illuminate/database: ^11.0
- staudenmeir/eloquent-has-many-deep-contracts: ^1.2
Requires (Dev)
- awobaz/compoships: ^2.3
- barryvdh/laravel-ide-helper: ^3.0
- korridor/laravel-has-many-merged: ^1.1
- larastan/larastan: ^3.0
- laravel/framework: ^11.0
- mockery/mockery: ^1.6
- orchestra/testbench-core: ^9.5
- phpunit/phpunit: ^11.0
- staudenmeir/eloquent-json-relations: ^1.11
- staudenmeir/laravel-adjacency-list: ^1.21
- dev-main
- v1.20.5
- v1.20.4
- v1.20.3
- v1.20.2
- v1.20.1
- v1.20
- 1.19.x-dev
- v1.19.4
- v1.19.3
- v1.19.2
- v1.19.1
- v1.19
- v1.18.3
- v1.18.2
- v1.18.1
- v1.18
- 1.17.x-dev
- v1.17.3
- v1.17.2
- v1.17.1
- v1.17
- v1.16
- v1.15.3
- v1.15.2
- v1.15.1
- v1.15
- 1.14.x-dev
- v1.14.4
- v1.14.3
- v1.14.2
- v1.14.1
- v1.14
- v1.13.1
- v1.13
- 1.12.x-dev
- v1.12
- 1.11.x-dev
- v1.11.1
- v1.11
- v1.10
- v1.9
- 1.8.x-dev
- v1.8
- 1.7.x-dev
- v1.7
- v1.6
- v1.5
- v1.4
- v1.3
- v1.2
- v1.1
- v1.0
- dev-php8.4
- dev-phpstan-test
- dev-descendants
This package is auto-updated.
Last update: 2024-11-27 22:32:38 UTC
README
This extended version of HasManyThrough
allows relationships with unlimited intermediate models.
It supports many-to-many and polymorphic relationships and all their possible combinations.
It also supports some third-party packages.
Supports Laravel 5.5+.
Installation
composer require staudenmeir/eloquent-has-many-deep:"^1.7"
Use this command if you are in PowerShell on Windows (e.g. in VS Code):
composer require staudenmeir/eloquent-has-many-deep:"^^^^1.7"
Versions
Usage
The package offers two ways of defining deep relationships:
You can concatenate existing relationships or specify the intermediate models,
foreign and local keys manually.
- Concatenating Existing Relationships
- Defining Relationships Manually
- Intermediate and Pivot Data
- Intermediate and Pivot Constraints
- Table Aliases
- Soft Deleting
- Getting Unique Results
- Reversing Relationships
- IDE Helper
Concatenating Existing Relationships
Consider this example from the Laravel documentation
with an additional level:
Country
→ has many → User
→ has many → Post
→ has many → Comment
You can define a HasManyDeep
relationship by concatenating existing relationships:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeepFromRelations($this->posts(), (new Post())->comments()); } public function posts() { return $this->hasManyThrough(Post::class, User::class); } } class Post extends Model { public function comments() { return $this->hasMany(Comment::class); } }
Define a HasOneDeep
relationship with hasOneDeepFromRelations()
if you only want to retrieve a single related
instance.
Constraints
By default, constraints from the concatenated relationships are not transferred to the new deep relationship.
Use hasManyDeepFromRelationsWithConstraints()
with the relationships as callable arrays to apply these constraints:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeepFromRelationsWithConstraints([$this, 'posts'], [new Post(), 'comments']); } public function posts() { return $this->hasManyThrough(Post::class, User::class)->where('posts.published', true); } } class Post extends Model { public function comments() { return $this->hasMany(Comment::class)->withTrashed(); } }
Make sure to qualify the constraints' column names if they appear in multiple tables:
->where('posts.published', true)
instead of ->where('published', true)
Third-Party Packages
Besides native Laravel relationships, you can also concatenate relationships from these third-party packages:
- https://github.com/korridor/laravel-has-many-merged:
HasManyMerged
- https://github.com/staudenmeir/eloquent-json-relations:
BelongsToJson
,HasManyJson
,HasManyThroughJson
- https://github.com/staudenmeir/laravel-adjacency-list: Tree & Graph relationships
- https://github.com/topclaudy/compoships:
BelongsTo
,HasMany
,HasOne
Defining Relationships Manually
If you don't have all the necessary existing relationships to concatenate them, you can also define a deep relationship manually by specifying the intermediate models, foreign and local keys.
HasMany
Consider this example from the Laravel documentation
with an additional level:
Country
→ has many → User
→ has many → Post
→ has many → Comment
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]); } }
Just like with hasManyThrough()
, the first argument of hasManyDeep()
is the related model. The second argument is an
array of intermediate models, from the far parent (the model where the relationship is defined) to the related model.
By default, hasManyDeep()
uses the Eloquent conventions for foreign and local keys. You can also specify custom
foreign keys as the third argument and custom local keys as the fourth argument:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Comment::class, [User::class, Post::class], // Intermediate models, beginning at the far parent (Country). [ 'country_id', // Foreign key on the "users" table. 'user_id', // Foreign key on the "posts" table. 'post_id' // Foreign key on the "comments" table. ], [ 'id', // Local key on the "countries" table. 'id', // Local key on the "users" table. 'id' // Local key on the "posts" table. ] ); } }
You can use null
placeholders for default keys:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class], [null, 'custom_user_id']); } }
ManyToMany
You can include ManyToMany
relationships in the intermediate path.
ManyToMany → HasMany
Consider this example from the Laravel documentation
with an additional HasMany
level:
User
→ many to many → Role
→ has many → Permission
Add the pivot tables to the intermediate models:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Permission::class, ['role_user', Role::class]); } }
If you specify custom keys, remember to swap the foreign and local key on the "right" side of the pivot table:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Permission::class, ['role_user', Role::class], // Intermediate models and tables, beginning at the far parent (User). [ 'user_id', // Foreign key on the "role_user" table. 'id', // Foreign key on the "roles" table (local key). 'role_id' // Foreign key on the "permissions" table. ], [ 'id', // Local key on the "users" table. 'role_id', // Local key on the "role_user" table (foreign key). 'id' // Local key on the "roles" table. ] ); } }
ManyToMany → ManyToMany
Consider this example from the Laravel documentation
with an additional ManyToMany
level:
User
→ many to many → Role
→ many to many → Permission
Add the pivot table to the intermediate models:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Permission::class, ['role_user', Role::class, 'permission_role']); } }
MorphMany
You can include MorphMany
relationships in the intermediate path.
Consider this example from the Laravel
documentation with an additional level:
User
→ has many → Post
→ morph many → Comment
Specify the polymorphic foreign keys as an array, starting with the *_type
column:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function postComments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Comment::class, [Post::class], [null, ['commentable_type', 'commentable_id']] ); } }
MorphToMany
You can include MorphToMany
relationships in the intermediate path.
Consider this example from the
Laravel documentation with an additional level:
User
→ has many → Post
→ morph to many → Tag
Add the pivot table to the intermediate models and specify the polymorphic foreign keys as an array, starting with
the *_type
column:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function postTags(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Tag::class, [Post::class, 'taggables'], [null, ['taggable_type', 'taggable_id'], 'id'], [null, null, 'tag_id'] ); } }
Remember to swap the foreign and local key on the "right" side of the pivot table:
MorphedByMany
You can include MorphedByMany
relationships in the intermediate path.
Consider this example from the
Laravel documentation with an additional level:
Tag
→ morphed by many → Post
→ has many → Comment
Add the pivot table to the intermediate models and specify the polymorphic local keys as an array, starting with
the *_type
column:
class Tag extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function postComments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Comment::class, ['taggables', Post::class], [null, 'id'], [null, ['taggable_type', 'taggable_id']] ); } }
BelongsTo
You can include BelongsTo
relationships in the intermediate path:
Tag
→ morphed by many → Post
→ belongs to → User
Swap the foreign and local key:
class Tag extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function postAuthors(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( User::class, ['taggables', Post::class], [null, 'id', 'id'], [null, ['taggable_type', 'taggable_id'], 'user_id'] ); } }
HasOneDeep
Define a HasOneDeep
relationship if you only want to retrieve a single related instance:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function latestComment(): \Staudenmeir\EloquentHasManyDeep\HasOneDeep { return $this->hasOneDeep(Comment::class, [User::class, Post::class]) ->latest('comments.created_at'); } }
Composite Keys
If multiple columns need to match between two tables, you can define a composite key with the CompositeKey
class.
Consider this example from the compoships
documentation with an
additional level:
User
→ has many (matching team_id
& category_id
) → Task
→ belongs to → Project
use Staudenmeir\EloquentHasManyDeep\Eloquent\CompositeKey; class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function projects(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep( Project::class, [Task::class], [new CompositeKey('team_id', 'category_id'), 'id'], [new CompositeKey('team_id', 'category_id'), 'project_id'] ); } }
Intermediate and Pivot Data
Use withIntermediate()
to retrieve attributes from intermediate tables:
public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]) ->withIntermediate(Post::class); } foreach ($country->comments as $comment) { // $comment->post->title }
By default, this will retrieve all the table's columns. Be aware that this executes a separate query to get the list of columns.
You can specify the selected columns as the second argument:
public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]) ->withIntermediate(Post::class, ['id', 'title']); }
As the third argument, you can specify a custom accessor:
public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]) ->withIntermediate(Post::class, ['id', 'title'], 'accessor'); } foreach ($country->comments as $comment) { // $comment->accessor->title }
If you retrieve data from multiple tables, you can use nested accessors:
public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]) ->withIntermediate(Post::class) ->withIntermediate(User::class, ['*'], 'post.user'); } foreach ($country->comments as $comment) { // $comment->post->title // $comment->post->user->name }
Use withPivot()
for the pivot tables of BelongsToMany
and MorphToMany
/MorphedByMany
relationships:
public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Permission::class, ['role_user', Role::class]) ->withPivot('role_user', ['expires_at']); } foreach ($user->permissions as $permission) { // $permission->role_user->expires_at }
You can specify a custom pivot model as the third argument and a custom accessor as the fourth:
public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Permission::class, ['role_user', Role::class]) ->withPivot('role_user', ['expires_at'], RoleUser::class, 'pivot'); } foreach ($user->permissions as $permission) { // $permission->pivot->expires_at }
Intermediate and Pivot Constraints
You can apply constraints on intermediate and pivot tables:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]); } } $commentsFromActiveUsers = $country->comments()->where('users.active', true)->get();
Table Aliases
If your relationship path contains the same model multiple times, you can specify a table alias:
class Post extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function commentReplies(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [Comment::class . ' as alias'], [null, 'parent_id']); } }
Use the HasTableAlias
trait in the models you are aliasing:
class Comment extends Model { use \Staudenmeir\EloquentHasManyDeep\HasTableAlias; }
For pivot tables, this requires custom models:
class User extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function permissions(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Permission::class, [RoleUser::class . ' as alias', Role::class]); } } class RoleUser extends Pivot { use \Staudenmeir\EloquentHasManyDeep\HasTableAlias; }
Use setAlias()
to specify a table alias when concatenating existing relationships:
class Post extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function commentReplies(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeepFromRelations( $this->comments(), (new Comment())->setAlias('alias')->replies() ); } public function comments() { return $this->hasMany(Comment::class); } } class Comment extends Model { use \Staudenmeir\EloquentHasManyDeep\HasTableAlias; public function replies() { return $this->hasMany(self::class, 'parent_id'); } }
Soft Deleting
By default, soft-deleted intermediate models will be excluded from the result. Use withTrashed()
to include them:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]) ->withTrashed('users.deleted_at'); } } class User extends Model { use SoftDeletes; }
Getting Unique Results
Deep relationships with many-to-many segments can contain duplicate models in their results. If you want to get unique results, you can remove duplicates from the result collection:
$uniqueComments = Country::find($id)->comments()->get()->unique();
If you need to remove duplicates in the query (e.g. for pagination), try adding distinct()
:
$uniqueComments = Country::find($id)->comments()->distinct()->get();
distinct()
doesn't work for all cases. If it doesn't work for you, use groupBy()
instead:
$uniqueComments = Country::find($id)->comments() ->getQuery() // Get the underlying query builder ->select('comments.*') // Select only columns from the related table ->groupBy('comments.id') // Group by the related table's primary key ->get();
Reversing Relationships
You can define a HasManyDeep
/HasOneDeep
relationship by reversing an existing deep relationship
using hasManyDeepFromReverse()
/hasOneDeepFromReverse()
:
class Country extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function comments(): \Staudenmeir\EloquentHasManyDeep\HasManyDeep { return $this->hasManyDeep(Comment::class, [User::class, Post::class]); } } class Comment extends Model { use \Staudenmeir\EloquentHasManyDeep\HasRelationships; public function country(): \Staudenmeir\EloquentHasManyDeep\HasOneDeep { return $this->hasOneDeepFromReverse( (new Country())->comments() ); } }
IDE Helper
If you are using barryvdh/laravel-ide-helper, this package provides a model hook that will correctly add relations when generating the type hints. The model hook is enabled by default using Package Discovery.
To enable it manually, add model hook to the model_hooks array.
// File: config/ide-helper.php /* |-------------------------------------------------------------------------- | Models hooks |-------------------------------------------------------------------------- | | Define which hook classes you want to run for models to add custom information | | Hooks should implement Barryvdh\LaravelIdeHelper\Contracts\ModelHookInterface. | */ 'model_hooks' => [ \Staudenmeir\EloquentHasManyDeep\IdeHelper\DeepRelationsHook::class, ],
To disable the model hook you have 3 options:
Disable using .env
Update your .env
file to include:
ELOQUENT_HAS_MANY_DEEP_IDE_HELPER_ENABLED=false
Disable using config
Publish the config and disable the setting directly:
php artisan vendor:publish --tag=eloquent-has-many-deep
// File: config/eloquent-has-many-deep.php /* |-------------------------------------------------------------------------- | IDE Helper |-------------------------------------------------------------------------- | | Automatically register the model hook to receive correct type hints | */ 'ide_helper_enabled' => false,
Disable by opting out of Package Discovery
Update your composer.json
with the following:
"extra": { "laravel": { "dont-discover": [ "staudenmeir/eloquent-has-many-deep" ] } },
Contributing
Please see CONTRIBUTING and CODE OF CONDUCT for details.