Getting Started

Install with composer require <vendor>/<package> and publish the config/migrations (php artisan vendor:publish --provider="...") before touching any models.
Look first at the package config file — it is the source of truth for which model classes the package resolves. Everything else (relations, policies, factories) hangs off those mappings.
Confirm the service provider bindings with php artisan tinker (app(YourModelContract::class)) before writing feature code; mismatches here surface later as confusing "wrong class" bugs.
First use case: scaffold a record through the package's factory in a test, then assert get_class($record) matches your configured model. This is the quickest smoke test that config, container bindings, and factories all agree.

Implementation Patterns

Configure, don't hardcode. Reference the package's config keys (or the published model map) rather than importing concrete classes directly. This keeps host-level swaps working and makes the package's resolution logic the single point of truth.
Swap in tests, not in production code. Point the config at a test double or extended model inside a test case's setUp()/defineEnvironment(), then let factories and the container do the rest. Reset config in tearDown() or use Laravel's config isolation.
Extend the package factory, don't replace it. Add states (->published(), ->forOwner($user)) on top of the shipped factory so future package fixes — including factory/model resolution fixes — flow through automatically.
Resolve through the container. Prefer app(PostContract::class) or the package's resolver helper over new Post. Any instanceof check or direct new is a place a host swap silently breaks.
Keep the swap surface small. When swapping a model, update in one pass: config mapping, morph map entries, factory $model, policies/gates, and any whereMorphedTo/relation usage. A checklist in your upgrade notes pays for itself.
Host-app integration tip: if you expose the package to downstream consumers, allow the model map to be overridden via config and document the factory contract — that is exactly the seam the 1.1.2 fix protects.

Upgrade to 1.1.2 if you swap models. Prior versions could have factories build the default model rather than the configured one when a host swapped it, producing records of the wrong class in tests and seeders. The symptom is subtle: assertions pass on attributes but instanceof/policy checks fail.
config:cache is the usual culprit. After changing a model mapping, run php artisan config:clear (and optimize:clear in CI) — cached config will keep serving the old class.
Swapping models doesn't move data. The new model must point at the same table, or you need a migration. Watch foreign keys and pivot tables that reference the old table name.
Morph maps drift. If the package stores polymorphic relations, register the swapped class in Relation::enforceMorphMap() before the package boots, or stored/retrieved types won't line up.
Debugging tip: get_class($factory->make()) and get_class(app(Contract::class)) in tinker will localize a resolution bug to config, container, or factory in seconds.
Extension point: the container binding is the sanctioned override. Avoid subclassing internals; bind your model (or a decorator) instead so package upgrades stay painless.
Pin the version in composer if your test suite depends on factory/model resolution, and add a regression test asserting the configured model is built — it will catch this class of bug on future upgrades.