Weave Code
Laravel Composite Relations Laravel Package
reedware/laravel-composite-relations
Adds composite foreign key support to Eloquent relationships. Define Belongs To, Has One, and Has Many relations using multiple columns, with full eager loading and "where has" query support through a simple trait on your base model.
Laravel Composite Relations adds native-feeling support for composite foreign keys in Eloquent relationships, a feature Eloquent lacks out of the box. Just include the package trait on your base model and define Belongs To, Has One, and Has Many relations using multiple key pairs—no service provider or facade required.
- Supports Belongs To, Has One, and Has Many composite relations
- Full eager loading support for composite keys
- Existence queries work as expected (e.g.
whereHas) - Drop-in trait integration on your base model
- Compatible with Laravel 12.x/13.x and PHP 8.2+
Frequently asked questions about Laravel Composite Relations
- What does reedware/laravel-composite-relations do?
- It adds composite key support to Laravel Eloquent relationships, letting you define Belongs To, Has One, and Has Many relations using multiple foreign keys. It preserves normal Eloquent behavior such as lazy loading, eager loading, and whereHas existence queries. It does not add composite belongsToMany, polymorphic, or hasManyThrough relations.
- How do I install reedware/laravel-composite-relations in Laravel?
- Install it with composer require reedware/laravel-composite-relations. There is no service provider or facade to register; instead, add the HasCompositeRelations trait to your base model. Then define composite relations using array keys for the local and foreign columns.
- Which Laravel and PHP versions does laravel-composite-relations support?
- Version support follows Laravel's release policy. Package v6 targets Laravel 12.x and 13.x with PHP 8.2 through 8.5+, while v5 targets Laravel 11.x and 12.x with PHP 8.2 through 8.4+. Older package majors map to older Laravel and PHP lines, so match the package major to your app's framework version.
- Which Eloquent relationships can use composite keys with this package?
- The package supports composite Belongs To, Has One, and Has Many relationships. It intentionally does not support composite belongsToMany, polymorphic, or hasManyThrough relations, and the README states there is no current intention to add them. Check your required relation types before adopting it.
- Does laravel-composite-relations support eager loading and whereHas?
- Yes. All composite relations support eager loading and existence queries such as whereHas, so they can fit into normal Eloquent query patterns. You should still test generated SQL and result sets for each relation because composite key matching can over-match if the glue is wrong.
- How do I define a composite belongsTo relation in Laravel?
- Add the HasCompositeRelations trait to your base model, then use compositeBelongsTo with array keys for the local and foreign columns. Use explicit glue where needed and verify the generated SQL with positive and negative fixtures. The same array-key approach applies to compositeHasOne and compositeHasMany.
- What is the 'or' glue risk in laravel-composite-relations?
- The default glue between composite key pairs is 'or', which can match more rows than intended across multiple key pairs. For correctness-critical relations, define explicit 'and' glue and enforce it in code review and SQL-level tests. Each composite relation should prove it does not over-match rows.
- Can I use relation joins with composite relations?
- Optional relation joins require the separate reedware/laravel-relation-joins package. The core composite relations package does not provide those joins by itself. Confirm whether your use case needs joins before adding the companion dependency.
- Is laravel-composite-relations safe for production use?
- It can be a precision dependency for apps with externally fixed composite-key schemas, but it is single-maintainer with low adoption and no community backstop. Pin the package major, mandate explicit 'and' glue, add SQL-level tests for every composite relation, and name an internal owner who can review generated SQL and fork if needed. Avoid treating it as a platform bet.
- What are alternatives to laravel-composite-relations?
- If you own the schema, surrogate keys and native single-key Eloquent relations are usually the cheaper long-term design. If the schema is fixed or externally owned, the alternatives are hand-rolled joins per query or this package's composite relation API. The package is most useful when you want Eloquent-style eager loading and whereHas without rewriting every read path.
Weaver
How can I help you explore Laravel packages today?