Options For Laravel Laravel Package

Getting Started

• Install the package with Composer and let Laravel's package discovery register the service provider. Publish the package config (php artisan vendor:publish) so you can see the model map — this map is the seam a host application uses to swap models.
• Look first at the config file and any model resolver/binding the package registers. That is where "the configured model" is decided, and therefore where a host app overrides it.
• First use case: in a host app (or in a package's own test suite), point the config at your own model subclass, then create a record through a factory. The factory should instantiate the swapped class, not the package default. As of 1.1.2 this is the expected behavior; on earlier versions you would have seen the default model built instead.

Implementation Patterns

• Config-driven swaps: Override the package's model mapping in config/your-package.php (or at runtime with config()->set(...)) rather than subclassing internals. Keep swaps to subclasses that preserve the expected contract/interface so the rest of the package keeps working.
• Factory-as-verification: Treat Model::factory()->create() against a swapped model as your smoke test. If the factory returns an instance of your swapped class, the resolution path is wired correctly end-to-end.
• Test-time swaps: Use config()->set() in setUp()/beforeEach or a dedicated helper to swap the model for a test double, then assert on the class the factory produced (assertInstanceOf). Pair with RefreshDatabase as usual.
• Avoid hardcoded classes: In your own code and tests, resolve models through the package's resolver/container binding (app(...), resolve(...)) or via the configured key, never new DefaultModel. Hardcoded new calls bypass the swap and reintroduce the exact bug 1.1.2 fixed.
• Host integration: If you maintain a package that others embed, document the model map as a public extension point and have your own factories go through the resolver so downstream hosts get correct instances automatically.
• Factory customization: When overriding a factory's newModel()/definition, pull the class from the configured map instead of returning a literal class name, so host swaps propagate into your factory too.

Gotchas and Tips

• Upgrade cleanup: If you were on ≤1.1.1, remove any workarounds you added to force factories to build swapped models (e.g., manual factory()->newModel() overrides or Model::unguard-style hacks). 1.1.2 makes this native; leaving workarounds in place can cause double-overrides or confusing test failures.
• Config caching: Model maps are read from config. After editing the mapping, run php artisan config:clear (and be aware config:cache bakes the map in), otherwise your swap silently won't apply.
• Order of operations: Swap the model before the factory is invoked. Factories resolved at definition time vs. call time can behave differently — if a swap seems ignored, check whether the factory cached a class early.
• Resolution, not instantiation: Ensure your factories and any custom code use container resolution (app(), resolve()) or the package's resolver. Direct new instantiation will always build the default class, regardless of config.
• Debugging: dd(get_class($model)) inside a factory callback, or assert get_class(...) in a test, is the fastest way to confirm which class is actually being built. Also dump the resolved config key (config('your-package.models...')) to verify the cached value.
• Extension points: The model map and the resolver binding are the intended customization surfaces. Prefer binding a custom resolver over monkey-patching factories; if you must extend a factory, override newModel() and delegate to the resolver rather than duplicating class literals.
• Contract discipline: Swapped models must honor the same interface/columns the package expects. A swap that changes schema or method signatures will pass factory creation but fail later in package logic — test beyond the factory call.