What this PR does

Adds an only() method to Illuminate\Database\Eloquent\Factories\Factory that gives callers fine-grained control over which related factories are expanded when building or creating models in tests. It also ships two opt-in global settings — Factory::onlyByDefault() and Factory::inferRequiredForeignKeys() — that make the behaviour automatic across a whole test suite.

Problem

Every factory definition() that includes a BelongsTo factory (e.g. 'user_id' => UserFactory::new()) will create that parent model unconditionally, even when the test being written doesn't care about it. On large schemas this silently creates many rows, pollutes assertions, slows down test suites, and produces hard-to-debug failures caused by unexpected related data. withoutParents() exists but is all-or-nothing; there was previously no way to say "create only this specific set of relations and ignore the rest".

Solution

->only(...$relationships) — whitelist which related factories in the definition should be expanded. All other factory-typed attributes are set to null; scalar attributes are left untouched so that states applied before or after only() are never clobbered.

// Only create the post's author — do not create any other related models.
$post = PostFactory::new()->only('author')->make();

// Dot-notation to restrict a nested factory too.
$post = PostFactory::new()->only('author.team')->make();

// No args = strip everything.
$post = PostFactory::new()->only()->make();

States always take precedence, regardless of chain order. The method is implemented as a first-class factory property (not another state closure), so definition() is called exactly once and PHP object identity (===) reliably distinguishes a definition-default factory from one explicitly set by a state:

// All three preserve the state's value.
PostFactory::new()->state(['user_id' => 99])->only()->make();
PostFactory::new()->state(['user_id' => UserFactory::new()])->only()->make();
PostFactory::new()->only()->state(['user_id' => UserFactory::new()])->make();

$required property — per-factory class override for relations that must always survive only(), regardless of what the caller passes:

class OrderFactory extends Factory
{
    protected $required = ['customer']; // always created, even with ->only()
}

Factory::onlyByDefault() — activates only() globally so factories strip unwhitelisted relations without any per-factory call. Equivalent to implicitly calling ->only() on every factory. The $required property is still respected. Configurable via config/database.php:

// AppServiceProvider::boot()
Factory::onlyByDefault();
// or config: DB_FACTORY_ONLY_BY_DEFAULT=true

Factory::inferRequiredForeignKeys() — when only() is active (explicitly or globally), inspects the database schema to find BelongsTo relationships whose FK column is NOT NULL and automatically adds them to the whitelist. This means truly required parents are never accidentally stripped. Schema results are cached per model class for the lifetime of the process — exactly one getColumns() call per model class per test suite run, regardless of how many factories or assertions use that model. Configurable:

Factory::inferRequiredForeignKeys();
// or config: DB_FACTORY_INFER_REQUIRED_FOREIGN_KEYS=true

Per-factory resolver callbacks — for cases where the global flags need different behaviour on a factory-by-factory basis:

Factory::resolveOnlyByDefaultUsing(
    fn ($factory) => $factory instanceof MyBaseFactory
);

Factory::resolveInferRequiredForeignKeysUsing(
    fn ($factory) => ! ($factory instanceof LegacyFactory)
);

Resolution order for each flag: resolver callback → static flag → config → false.

Why this does not break existing features

• only() is purely additive; no existing call sites are changed.
• onlyByDefault and inferRequiredForeignKeys default to false (both in the static property and in config/database.php), so existing applications are entirely unaffected unless they opt in.
• flushState() resets all new static properties and resolvers, matching the existing pattern used by expandRelationshipsByDefault. The schema cache ($schemaRequiredForeignKeys) is intentionally not reset — the schema does not change between tests.
• The applyOnlyFilter step runs after all states have been accumulated, so every existing chaining pattern (->state(), ->for(), ->has(), ->recycle(), ->count(), ->sequence(), ->withoutParents()) continues to behave exactly as before when only() is not involved.

Database support

Schema inspection uses SchemaBuilder::getColumns(), which normalises the nullable flag across all four Laravel-supported drivers: MySQL/MariaDB, PostgreSQL, SQLite, and SQL Server. If the connection is unavailable or the driver does not support column introspection, resolveRequiredForeignKeyRelations() fails gracefully and returns [], leaving the whitelist unchanged.

Defining required foreign keys directly on models and in tests is generally preferable. Factory::inferRequiredForeignKeys() is provided as a convenience for codebases adopting only() via Factory::onlyByDefault() — it means existing tests don't all need updating at once, giving a "fastest path to faster tests" on legacy codebases.

The more likely long-term approach is to configure requirements per model or test as needed. This doesn't take long even on a large codebase: $required only needs defining once per factory, failures are loud and obvious, and the per-test cases are easy to handle with a Foo::factory() → Foo::factory()->only('bar') find-and-replace.