Teams For Laravel Laravel Package

Getting Started

• Install with composer require vendor/package, then publish the package assets: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (publish the config and migrations tags separately if you only need one).
• Run php artisan migrate and open config/package.php first. The models array is the contract between the package and your app — it maps package concepts to concrete Eloquent classes, and it is what the 1.0.4 factory fix keys off of.
• Next, read the shipped factories under database/factories and the bindings in the service provider. Between the config map, the provider bindings, and the factories you have the whole surface area of the package.
• First use case: in a feature test, create a record with PackageModel::factory()->create() and assert your app's behaviour around it. If you plan to extend or replace the package model, change the config entry to your subclass and re-run the test — as of 1.0.4 the factory will build your class, not the package's hardcoded one.

Implementation Patterns

Factory-first testing. Treat the package factories as the supported entry point for fixtures. Use states and relationship helpers rather than hand-rolling attributes, so that when the model map changes, your tests keep working:

$order = Order::factory()->for($user)->hasItems(3)->create();

Swapping models in a host app. Point the config at your subclass, then extend the package model so you inherit the package's traits and scopes:

// config/package.php
'models' => [
    'order' => App\Models\Order::class,
],

// app/Models/Order.php
class Order extends Vendor\Package\Models\Order
{
    protected $table = 'orders';
}

The 1.0.4 change is what makes this dependable in tests: Order::factory() now instantiates the configured class, so overrides, casts, global scopes, and observers you added in App\Models\Order actually apply to factory-created records.

Prefer the container over new. Where the package resolves models or services through the container, mirror that in your own code (app(OrderContract::class)), so a config swap propagates to your integration points as well as the package's.

Seeders. Reuse the package factories in seeders for local and staging environments, and gate them behind app()->environment() so demo data never lands in production.

Testing the swap itself. Add one small test that asserts the resolved class, so a future config change doesn't silently revert you to package defaults:

$this->assertInstanceOf(App\Models\Order::class, Order::factory()->make());

Integration tips. Register observers, policies, and route model bindings against your subclass in your own provider — the package's provider binds its own defaults, and ordering matters if you override bindings after it ($this->app->afterResolving(...) is often cleaner than bind in a later provider).

Gotchas and Tips

• 1.0.4 is the release that makes model swapping work in factories. On earlier versions, factories built the hardcoded package model even when your config pointed elsewhere, so you'd get the wrong class in tests with no clear error — your casts, $fillable, and observers were silently ignored. Upgrade and re-run any test that relies on a swapped model, since previously "passing" tests may have been asserting against the wrong instance.
• Clear compiled config after editing the map. php artisan config:clear (and config:cache in deploy). A stale cached config is the single most common reason a swap appears not to take effect.
• Factory name resolution still follows Laravel conventions. If your swapped model lives in a different namespace, Laravel may not find a factory for it. Add newFactory() to your subclass or a Factory::guessFactoryNamesUsing() callback rather than duplicating the package factory.
• $table and foreign keys are on you. Swapping the model does not rewrite migrations or relationship columns. If you rename tables, set $table explicitly and check belongsTo/hasMany foreign key names in the package's relations.
• Migrations published from the package are a snapshot. If you need schema changes for your subclass, add your own migration rather than editing the published one, so package upgrades don't clobber it.
• Debugging the swap. get_class(Order::factory()->make()) tells you immediately which class the factory resolved; config('package.models.order') tells you what it should be. If they disagree, it's cache or a provider boot order issue.
• Extension points to reach for before forking. The model map, the published config, container bindings, model states on factories, and model observers cover most customisation. Reach for a subclass only when you need new columns or behaviour; reach for a fork only when the package hardcodes a class outside the config map.