Weave Code
Custom Relation Laravel Package
culturegr/custom-relation
Easily define custom relationships between Eloquent models, like connecting users to permissions through roles. Includes an Artisan generator and full support for eager-loading, making complex multi-table joins clean and reusable.
culturegr/custom-relation is a Laravel package for defining custom relationships between Eloquent models when standard relations don't fit. A dedicated CustomRelation class encapsulates the join logic and supports eager-loading, keeping complex chains like User → Role → Permission clean and reusable.
A make:relation Artisan command scaffolds boilerplate classes in app/Eloquent/CustomRelations, and the service provider is auto-discovered on Laravel 5.5+.
- Dedicated
CustomRelationclass for join logic - Native eager-loading support
make:relationArtisan generator- Auto-discovered service provider
- Ideal for multi-hop relations (User → Role → Permission)
Frequently asked questions about Custom Relation
- How do I install culturegr/custom-relation in a Laravel app?
- Install it with Composer by running composer require culturegr/custom-relation. On Laravel 5.5 and above the CustomRelationServiceProvider is auto-discovered, so no manual registration is needed. If discovery is disabled in your application, add CultureGr\CustomRelation\CustomRelationServiceProvider::class to the providers array in config/app.php. No configuration files or migrations are published during installation.
- What problem does a custom Eloquent relation solve that hasManyThrough does not?
- It handles relationships that span more than two intermediate tables or that need custom join logic, such as User to Role to Permission. Instead of writing repeated query-builder joins or loading intermediate models in PHP, you encapsulate the join logic in a single relation class and call it like a normal Eloquent relation. This keeps model code declarative and readable, and it works with existing schemas you cannot easily refactor.
- How do I generate a custom relation class with the make:relation command?
- Run php artisan make:relation UserPermissionRelation and the package creates a class in app/Eloquent/CustomRelations that extends CultureGr\CustomRelation\CustomRelation. The generated file contains the boilerplate query builder property and the methods you override to define the join and the related records. You then fill in the table joins and return the Eloquent collection of related models.
- Does culturegr/custom-relation support eager loading?
- Yes. Custom relation classes are built to support Eloquent eager loading, so you can use with() on the relation name to avoid the N+1 query problem. This makes it practical to load custom relations across a collection of models in a single query. Eager-loading behaviour follows the same constraints as native Eloquent relations, so verify it on your own data set for very complex joins.
- Which Laravel and PHP versions does culturegr/custom-relation support?
- The package advertises support from Laravel 5.5 through Laravel 13, with PHP 7.4 or higher as the historical floor. Note that each Laravel branch has its own PHP requirement — Laravel 11 and later need PHP 8.2+ — so confirm what composer.json on your target release actually allows rather than assuming the whole range is uniformly tested. Release v1.5.0 added Laravel 13 support as a minor, non-breaking version bump.
- Do I need to run migrations or change my database schema to use this package?
- No. The package ships no migrations or schema requirements and works against tables you already have. A custom relation simply describes how to join existing tables and which records to return. That makes it a good fit for legacy or multi-tenant databases where altering the schema is expensive or risky.
- How do I use a custom relation on a model, for example user->customPermissions()?
- Add a method to your model that returns an instance of your relation class, for example a permissions() method returning new UserPermissionRelation($this). Because it is declared as a method on the model, you can call it as a property such as $user->permissions or chain constraints on it. The relation class holds the join and query logic, keeping the model itself thin. You can then eager load it with User::with('permissions').
- Is culturegr/custom-relation actively maintained, and is it safe for production?
- The repository carries a GitHub Actions test badge and release v1.5.0 demonstrates active maintenance by adding Laravel 13 support without breaking changes. Two caveats remain: the package license is reported as NOASSERTION on Packagist, so check the repository for the actual terms before shipping it in commercial code, and confirm that CI covers your specific Laravel and PHP combination. The README offers limited guidance on edge cases such as circular or conflicting relations, so pilot it in one module first.
- How does the performance of custom relations compare to raw queries or hasManyThrough?
- The package does not publish benchmarks, so there is no official data comparing it to native hasManyThrough or hand-written joins. In practice the generated query is a standard Eloquent join, and most of the cost comes from join depth and indexing rather than the package itself. If the relation spans more than three tables or runs on large data sets, benchmark it against a raw query in your own application before relying on it in a hot path.
- What alternatives exist for complex Eloquent relationships in Laravel?
- Laravel's built-in hasManyThrough and hasOneThrough cover many multi-hop cases without extra dependencies. Packages such as staudenmeir/eloquent-has-many-deep support arbitrarily deep has-many chains and offer a well-documented alternative. You can also use subquery selects, raw joins, or dedicated query objects. Choose culturegr/custom-relation when you want a small, Eloquent-native class per relationship without adding heavier dependencies.
Weaver
How can I help you explore Laravel packages today?