Extra Foundry Bundle Laravel Package

Getting Started

• Install it as a dev-only dependency: composer require --dev <package>. Note that this release pins zenstruck/foundry: ^1.10.0, so you inherit that constraint — if your app or another package needs a newer Foundry, expect a resolution conflict at install time (see Gotchas).
• Look first at tests/Factory/ (or wherever the package expects factories) and at the factory base class it ships. That base class is where persistence, naming conventions, and Eloquent wiring are decided — read it before writing your first factory.
• The refreshed documentation links in this release are the fastest orientation path; the section on factory states and relationships is the one worth reading end-to-end on day one.
• First use case: take an existing integration test that hand-rolls setup like User::factory()->create() plus manually attached related records, and replace it with a single Foundry factory call that produces the same persisted graph. That gives you an immediate before/after on readability, and it exercises the persistence path (the part most likely to need config).

Implementation Patterns

• One factory per model, defaults in getDefaults(). Keep it declarative and boring; put anything conditional in a state method instead of an if inside the defaults.
• States as named methods that return $this->state([...]). published(), admin(), withSubscription() compose better in tests than passing raw attribute arrays and they act as a shared vocabulary across the test suite.
• Relationships via nested factories, sharing via recycle. 'author' => UserFactory::new() creates a fresh user each time; when a test needs the same user across many records, use recycling (->recycle($user) / the factory-level recycle API) instead of passing the instance into every attribute array. This is the single biggest lever on test runtime.
• Separate instantiation from persistence. Use the non-persisting path (new() / in-memory creation) for unit tests that only care about computed behaviour, and the persisting path (create() / createOne(), or your base class's save hook for Eloquent) for integration tests. Wrapping persistence in one place in the base factory keeps the rest of the suite version-agnostic.
• Bulk creation in integration tests. Prefer the many-record helpers over a for loop with create() in each iteration — fewer round trips and a much shorter call site.
• Faker inside defaults. Use the fake() helper for realistic values, but pass explicit values for anything a test asserts on. Seed Faker in CI for reproducibility when a failing assertion needs to be re-runnable.
• Pest/PHPUnit wiring. Create fixtures inside the test or setUp/beforeEach alongside RefreshDatabase so rollback covers everything; avoid building fixtures in beforeAll-style hooks where the transaction boundary doesn't apply.

Gotchas and Tips

• ^1.10 is a floor with an old ceiling. Several convenience APIs landed late in the 1.x line. Before copying a snippet from the current docs, confirm it exists in your resolved version (composer show zenstruck/foundry). Symptom of a mismatch is a BadMethodCallException on a method that is clearly documented.
• Composer conflict is the likely upgrade failure mode. If another dev dependency wants Foundry ^1.11+, you get a resolver error rather than a runtime bug. Fix by aligning on a single Foundry version across the project rather than by loosening this package's constraint locally.
• Eloquent mass assignment. If your factories populate through fill()/create(), $fillable/$guarded will silently drop attributes. Assert on persisted state (assertPersisted or a fresh DB read) rather than on the in-memory object, or bypass guards deliberately.
• Silent duplicate graphs. Nested factories are eager: every call to defaults spawns new related rows. Tests that "work" but are slow are usually missing recycling. Audit with query counts (DB::listen) on a representative test.
• Closure attributes are resolved at instantiation time, not when the factory is defined, so closures that read $this->... of another attribute can surprise you with ordering. Keep dependent defaults in one closure rather than chaining several.
• fake()->unique() exhausts. In bulk creation over a few thousand records or in a data provider that runs repeatedly in one process, unique() throws. Prefer sequences or a deterministic generator for high-volume fixtures.
• Debugging tip: build the object without persisting and dump it first. Most "wrong data" reports are a state not being applied (order matters: later state() calls override earlier ones) or an attribute being overwritten by a relationship default.
• Extension points worth using: a shared abstract base factory (persistence + naming), afterMaking/afterCreating hooks for side effects like attaching pivot rows, custom Faker providers for domain-realistic data, and composition of states rather than one mega-state.
• Doc links rot. This release only refreshed documentation URLs; if you have internal onboarding notes pointing at the old anchors, update them now, since old deep links no longer resolve.