- How do I install ardalanamini/laravel-custom-relation?
- Install it with Composer using composer require ardalanamini/laravel-custom-relation and pin an exact version such as 0.1.5. The package supports Laravel auto-discovery, so no manual service provider registration is implied by the release surface. There are no migrations to run and no config file to publish. Adoption is purely additive, so you can install it without touching existing models.
- Which Laravel and PHP versions does laravel-custom-relation support?
- The package is framework-coupled by design, so a reasonable target is Laravel 9 or newer on PHP 8.1 or newer, but the repository does not document a formal support matrix. There is no evidence in the v0.1.5 release of a CI matrix exercising specific Laravel or PHP combinations. Check the composer.json constraint resolved by the version you install and confirm it matches your application. Raise the supported matrix question with the maintainer before committing to a production upgrade path.
- When should I use a custom relation instead of hasMany or belongsTo?
- Reach for a custom relation only when you have genuinely recurring multi-table relationship patterns, such as composite keys, tenant-scoped joins, polymorphic variants, or computed relations. If standard hasMany, belongsTo, or morphMany already express the domain, a custom relation adds indirection without any payoff. A good signal is three to five relations currently duplicated as whereHas clauses or query scopes across multiple models. Extract one first and verify it reduces duplication before expanding.
- Does laravel-custom-relation support eager loading with with() and withCount()?
- This is not documented in the release under review, and the package depends on Eloquent internals such as Relation, HasOneOrMany, and the existence and constraint query hooks. Partial support for with() eager loading, has() and whereHas() existence queries, or withCount() aggregates can cause silent N+1 queries or wrong counts in production. Write a spike that asserts query counts and aggregate results before relying on the relation anywhere important. Treat full Eloquent query-hook parity as an assumption to verify, not a guarantee.
- Is v0.1.5 a breaking change for existing installs?
- v0.1.5 is a metadata-only release: a single pull request from a first-time contributor touching composer.json, with no source changes and no described behaviour change. The one way it can affect you is if that edit widened, narrowed, or otherwise altered a framework constraint. Run composer update and diff the resolved dependency tree, or check the composer.json diff directly. If the constraint range did not change for your environment, the release is effectively inert.
- Is laravel-custom-relation stable enough for production use?
- The 0.1.x version line signals an explicitly unstable API, so minor bumps may carry breaking changes and SemVer gives you no protection. The project also has a single maintainer and a very small contributor base, with no documented CI matrix or security policy visible in this release. That does not make it low quality, but it does mean you are accepting maturity and bus-factor risk. Mitigate by pinning exactly, keeping the abstraction behind a feature flag, and reviewing changelogs before every bump.
- How do I define my own custom relation class?
- The package lets you write a reusable relation class and expose it as a first-class method on your Eloquent models, rather than chaining ad-hoc query builder calls in each model. The exact extension contract, whether you extend a base class or implement an interface, should be confirmed from the README and source before building on it. Because that contract is not versioned explicitly at 0.1.x, treat your relation classes as code that may need adjustment on upgrades. Start with a single relation class and one consumer model to limit blast radius.
- Can I remove laravel-custom-relation if it does not work out?
- Yes. Adoption is purely additive: there are no migrations, no data changes, and no schema implications, so rollback is a composer remove plus reverting the model methods that referenced the custom relation classes. That cheap-to-try, cheap-to-abandon asymmetry is the strongest argument for evaluating it at all. Keep the custom relation isolated behind a feature-flagged code path so the revert is a small, reviewable change. Do not spread the new relation classes across hundreds of models until the abstraction has proven itself.
- How should I test a custom relation against my existing query scope?
- Write a parity test that compares the custom relation against the duplicated whereHas or scope logic it replaces. Assert both the result set and the query count so you catch silent N+1s as well as incorrect rows. Also cover the eager-loading path with with(), existence checks with has() and whereHas(), and aggregates with withCount() if you use them. Only expand the abstraction to other models once parity on the first case is demonstrated.
- What are the alternatives to laravel-custom-relation?
- The direct alternatives are Eloquent query scopes, reusable whereHas and with() clauses, or hand-writing your own Relation subclass inside your application. Packages such as staudenmeir's deep and multi-table relationship extensions cover specific recurring patterns without a general-purpose abstraction. If Laravel's built-in hasMany, belongsTo, or morphMany types cover your domain, staying with them is the lower-risk choice. Choose this package only when you have a genuinely recurring relationship shape that stock relations cannot express cleanly.