Attributes For Laravel Laravel Package

Getting Started

• Install the package with Composer, then publish its config and migrations:

  composer require <vendor>/<package>
  php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
  php artisan migrate
  

• Look first at the published config file (config/<package>.php). This is where the package's models, table names, and other bindings are declared. In 1.1.2 the important detail is that these configured model classes are now honored by the package's factories.
• First use case: create a record through the package's factory in a test or seeder, then assert you got the class you configured:

  $record = YourModel::factory()->create();
  
  $this->assertInstanceOf(YourModel::class, $record);
  

• If you have not swapped any models, you can start with the package defaults immediately — the 1.1.2 fix only changes behavior when a host application substitutes its own model class.

Implementation Patterns

• Config-driven model swapping. Point the package config at your own model class (usually a subclass of the package's base model) and let the container resolve it:

  // config/<package>.php
  'models' => [
      'thing' => App\Models\Thing::class,
  ],
  

• Subclass, don't fork. Extend the package model, override $table, $fillable, relationships, and add your domain logic. Keep the package's traits and casts intact so its internals keep working.
• Let factories follow the config. Since 1.1.2, Factory::make()/create() build whichever model is configured. Use the package factories in your own tests and seeders rather than hand-rolling model instances, so swaps are exercised automatically.
• Swap in a service provider. For multi-tenant or per-environment models, register the binding in a provider that runs before anything resolves a factory:

  public function register(): void
  {
      config(['<package>.models.thing' => TenantThing::class]);
  }
  

• Seeder pattern. Prefer the package factory over Model::create([...]) so seed data always matches the configured model and its states:

  Thing::factory()->count(25)->published()->create();
  

• Custom states stay portable. Define states on your host model's factory (or a package factory extension) and reuse them across tests; states are resolved against the configured model, not a hardcoded class.
• Observers and policies should be registered against the configured class (e.g. via resolve() or the config value), not the package's base class, so swapped models keep their hooks.

Gotchas and Tips

• Upgrade for the factory fix. Before 1.1.2, if your host swapped the model, factories could still build the package's base model. If you saw assertInstanceOf failures or missing host-model attributes in factory output, upgrading to 1.1.2 is the fix. There are no breaking changes in this patch.
• Clear config cache after swapping. php artisan config:clear (and re-cache in production) after changing model bindings; a stale cached config is the most common reason a swap "doesn't take."
• Swap before first resolution. Factories resolve the configured model at build time. If a binding is registered lazily (e.g. inside a request or test), do it in register()/setUp() before any factory call.
• Explicit $model still wins. If you override protected $model on a factory, that takes precedence over the config — useful for edge cases, but it bypasses the swap and can hide misconfiguration.
• Debugging swaps. Dump the actual class produced:

  dump(get_class(Thing::factory()->make()));
  

  and confirm the config value with config('<package>.models.thing').
• Extension points. Override newFactory() on your model to return a custom factory, add factory states/methods, and use the package's resolver/binding helper if it exposes one — these are the supported seams for host customization.
• Keep migrations in sync. If your host model points at a different table, publish and adjust the migration accordingly; the package won't create columns for a table it doesn't know about.
• Test the swap itself. Add one test that asserts the configured model is produced by the factory, so future package upgrades (which may touch resolution logic) fail loudly rather than silently reverting to the base model.