Advertisements For Laravel Laravel Package

Getting Started

1. composer require the package, then run php artisan vendor:publish and pick the package's provider/tag from the list — you want the config file at minimum, and the migrations if it ships any. Run php artisan migrate.

2. Look at the config file first. The important part is the model map (the package resolves model classes from config rather than hardcoding FQCNs). That map is the contract for everything else: factories, relationships, policies, and any resolveRelationUsing wiring.

3. Confirm the factory path works before writing anything custom. In tinker or a scratch test:

   $model = config('your-package.models.some_model');
   $instance = $model::factory()->create();
   dump(get_class($instance), $instance->getTable());
   

   The class in the dump must match your config, not the package's base class. As of 1.1.2 this holds even after a host swaps the model — before this patch, the factory built the package's hardcoded class, leaving you with a model whose table/fillable/casts didn't match your subclass.

4. First real use case: in a feature test, swap the package model for your app's subclass in a service provider's register(), then keep writing plain Model::factory()->create() calls. Everything downstream (factories, relations, assertions) follows the swap.

Implementation Patterns

The config-driven swap (the package's primary extension point).

// app/Models/Article.php
class Article extends \Vendor\Package\Models\Article
{
    protected $fillable = [/* widened */];
}

// config/your-package.php
'models' => [
    'article' => App\Models\Article::class,
],

Do the swap in a service provider's register() (or bootstrap/app.php), not lazily inside a controller or test method:

public function register(): void
{
    config(['your-package.models.article' => \App\Models\Article::class]);
}

Ordering matters — register it from a provider that boots before the package provider, otherwise singletons/relations that captured the class name in their own register() will hold the wrong one.

Factory composition in tests. Treat the package factories as fixtures and build graphs with them:

$article = Article::factory()
    ->has(Comment::factory()->count(3), 'comments')
    ->state(['tenant_id' => $tenant->id])
    ->create();

Use ->for(), ->has(), ->state(), ->sequence() rather than manual Model::create() — you get the package's defaults (required columns, sensible values) for free, and the 1.1.2 fix means those defaults are applied to your model class.

Per-test swaps without leakage. If your suite needs different models per test, swap and restore:

protected function swapModel(string $key, string $class): void
{
    $original = config("your-package.models.$key");
    config(["your-package.models.$key" => $class]);
    $this->beforeApplicationDestroyed(fn () => config(["your-package.models.$key" => $original]));
}

Config mutations leak across tests in the same process, and so does anything the container already resolved.

Seeders. Never hardcode the package FQCN in seeders — resolve through config (config('your-package.models.article')::factory()), otherwise a swap silently produces base-class rows that your app's subclass can't hydrate correctly (casts, appended attributes, observers).

Custom factories for a swapped model. If you need domain-specific states, publish/extend the factory and set protected $model = \App\Models\Article::class;. This is the one place the config map does not save you — see gotchas.

Gotchas and Tips

• Your own factory classes still hardcode the model. 1.1.2 fixed resolution for the package's factories; a factory you wrote with protected $model = BaseArticle::class will reproduce the old mismatch (wrong table, missing fillable, "class not found" on relations). Always set $model on custom factories to the swapped class.
• config:cache bakes the map. Runtime config()->set() calls still work, but anything resolved during bootstrap is stale. If you ship a swap in a provider, it runs on every request, cached or not — that's the safe place. Don't swap inside a test if CI runs with a cached config you didn't regenerate.
• Swap before first resolution. Relations, Relation::morphMap(), route model binding, and container singletons all capture class names. A late swap gives you "works in one test, breaks in another" behaviour.
• Morph maps and stored type columns. If the package writes model_type values, swapping the class changes what's written/expected. Keep your Relation::morphMap() aliases stable and backfill existing rows before/after the swap, or old records won't resolve.
• Keep the table. Subclasses should normally inherit $table and the package's migrations. Changing it breaks the package's foreign keys and its own queries.
• Debugging checklist for "factory ignored my swap": dd(config('your-package.models')) → dd((new (config('your-package.models.x')))->getTable()) → dd(Model::factory()::class) (the ::class on the instance catches a hardcoded factory). Check Model::$factoryResolver too if the app overrides factory resolution globally.
• Upgrading from ≤1.1.1 to 1.1.2 is a patch with no API changes, but any test that asserted the old behaviour — e.g. assertInstanceOf(BaseArticle::class, ...) where you expected the base class despite a swap, or snapshot/get_class() comparisons — will now fail. Re-run the suite and fix those assertions rather than pinning the old version; the new behaviour is the correct one.
• Extension points worth knowing: the config model map (primary), published migrations, factory $model/$states, model booted() hooks, and package events. Reach for the config map before subclassing internals.