Getting Started

Install the package with Composer, then confirm the service provider/trait autoloading in composer.json.
For 1.2.0, look first at the HasDynamicRelation trait namespace. This release changes the core trait namespace, so update any use statements, config references, or string-based class references before relying on runtime relations.
Apply the trait to the Eloquent model(s) that need dynamic relationship resolution. Start with one model and one runtime relation before rolling it out broadly.
First use case: define a relation whose target model, table, foreign key, or relation name is not known statically—e.g. tenant-specific models, configurable modules, or relations selected from admin configuration.
After registering the relation, use it like a normal Eloquent relation with with(), load(), whereHas(), or relation access. Verify the exact registration API against the package README/tests because 1.2.0 only documents the namespace change.

Implementation Patterns

Centralize dynamic relation registration in a service provider, model booted() method, or dedicated resolver class rather than scattering registrations across controllers.
Treat relation names as part of your application contract. Validate them before passing user/config input into dynamic registration, and keep a small allowlist when possible.
Use dynamic relations for multi-tenant or modular modelling where each tenant/module may map a relation to a different model or table.
Register relations before building queries that eager load or constrain them. For example, register first, then use Model::with('dynamicRelation') or whereHas('dynamicRelation').
In tests, cover both registration and query behavior: assert the relation resolves, then assert eager loading and whereHas work against it.
For integration-heavy apps, wrap dynamic relation registration in a small application service so it can be cached, logged, and tested independently of Eloquent boot logic.
During the 1.2.0 upgrade, search the codebase for the old HasDynamicRelation namespace and replace it with the new one. Run composer dump-autoload and the full test suite, especially tests that instantiate every model using the trait.

The 1.2.0 namespace change is upgrade-sensitive. It may not fail at install time; failures often appear only when the trait is autoloaded or a dynamic relation is used.
Dynamic relations are not statically obvious to IDEs and static analysers. Add tests and, where needed, PHPDoc hints for relation names used by your application.
Avoid relation-name collisions with real model methods/relations. A dynamic relation can shadow or be shadowed by an existing relation depending on resolution order.
Registration timing matters. Registering after a query is built can lead to “relation does not exist” errors during eager loading or whereHas.
If registration depends on config or tenant context, clear Laravel caches after changing that context and make sure the relation is registered consistently across queued jobs and HTTP requests.
Keep dynamic relation metadata cacheable where possible; avoid expensive model/table discovery on every request.
For extension points, prefer wrapping the trait’s registration API in your own resolver/service rather than modifying vendor code. This keeps future namespace or API changes isolated to one place.