Eloquent 팩토리

번역일: 2026년 6월 27일

Eloquent 팩토리

소개
모델 팩토리 정의
팩토리로 모델 생성하기
팩토리 관계(Relationships)

소개

테스트를 작성하거나 데이터베이스에 초기 데이터를 심을 때, 레코드를 직접 삽입해야 할 때가 있습니다. 각 컬럼 값을 일일이 지정하는 대신, Laravel은 Eloquent 모델마다 기본 속성값 집합을 정의할 수 있는 모델 팩토리 기능을 제공합니다.

팩토리 작성 방법을 살펴보려면 애플리케이션의 database/factories/UserFactory.php 파일을 열어보세요. 이 파일은 새 Laravel 프로젝트에 기본으로 포함되어 있습니다:

namespace Database\Factories;

use Illuminate\Database\Eloquent\Factories\Factory;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;

/**
 * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\User>
 */
class UserFactory extends Factory
{
    /**
     * 팩토리에서 현재 사용 중인 패스워드
     */
    protected static ?string $password;

    /**
     * 모델의 기본 상태를 정의합니다.
     *
     * @return array<string, mixed>
     */
    public function definition(): array
    {
        return [
            'name' => fake()->name(),
            'email' => fake()->unique()->safeEmail(),
            'email_verified_at' => now(),
            'password' => static::$password ??= Hash::make('password'),
            'remember_token' => Str::random(10),
        ];
    }

    /**
     * 이메일 주소가 미인증 상태임을 나타냅니다.
     */
    public function unverified(): static
    {
        return $this->state(fn (array $attributes) => [
            'email_verified_at' => null,
        ]);
    }
}

팩토리는 Laravel의 기본 Factory 클래스를 상속받아 definition 메서드를 정의하는 클래스입니다. definition 메서드는 해당 팩토리로 모델을 생성할 때 적용할 기본 속성값 배열을 반환합니다.

fake() 헬퍼를 통해 팩토리에서는 Faker PHP 라이브러리를 사용할 수 있습니다. 이를 이용하면 테스트와 시딩에 필요한 다양한 랜덤 데이터를 편리하게 생성할 수 있습니다.

NOTE

config/app.php의 faker_locale 옵션을 변경하면 Faker의 로케일을 바꿀 수 있습니다. 한국어 데이터를 생성하려면 'faker_locale' => 'ko_KR'로 설정하세요.

모델 팩토리 정의

팩토리 생성

팩토리를 만들려면 make:factory Artisan 명령어를 실행합니다:

php artisan make:factory PostFactory

생성된 팩토리 클래스는 database/factories 디렉터리에 위치합니다.

모델과 팩토리 탐색 규칙

팩토리를 정의한 후에는 Illuminate\Database\Eloquent\Factories\HasFactory 트레이트가 제공하는 정적 factory 메서드를 모델에서 호출해 팩토리 인스턴스를 얻을 수 있습니다.

HasFactory 트레이트의 factory 메서드는 규칙에 따라 적절한 팩토리를 자동으로 찾습니다. 구체적으로는 Database\Factories 네임스페이스에서 모델명 뒤에 Factory가 붙은 클래스를 탐색합니다. 이 규칙이 프로젝트 구조와 맞지 않는 경우, UseFactory 속성(attribute)을 모델에 직접 지정할 수 있습니다:

use Illuminate\Database\Eloquent\Attributes\UseFactory;
use Database\Factories\Administration\FlightFactory;

#[UseFactory(FlightFactory::class)]
class Flight extends Model
{
    // ...
}

또는 모델에서 newFactory 메서드를 오버라이드하여 팩토리 인스턴스를 직접 반환하도록 할 수도 있습니다:

use Database\Factories\Administration\FlightFactory;

/**
 * 모델에 대한 새 팩토리 인스턴스를 생성합니다.
 */
protected static function newFactory()
{
    return FlightFactory::new();
}

이 경우 팩토리 클래스에는 model 프로퍼티를 정의해야 합니다:

use App\Administration\Flight;
use Illuminate\Database\Eloquent\Factories\Factory;

class FlightFactory extends Factory
{
    /**
     * 팩토리에 대응하는 모델 클래스명
     *
     * @var class-string<\Illuminate\Database\Eloquent\Model>
     */
    protected $model = Flight::class;
}

팩토리 상태(State)

상태(State) 메서드를 사용하면 팩토리의 기본 속성값을 부분적으로 변경하는 메서드를 여러 개 만들고, 조합해서 사용할 수 있습니다. 예를 들어 UserFactory에 suspended 상태 메서드를 추가해 계정 상태를 변경할 수 있습니다.

상태 메서드는 보통 기본 팩토리 클래스의 state 메서드를 호출합니다. state 메서드는 팩토리의 원시 속성 배열을 받아 변경할 속성 배열을 반환하는 클로저를 인자로 받습니다:

use Illuminate\Database\Eloquent\Factories\Factory;

/**
 * 사용자가 정지(suspended) 상태임을 나타냅니다.
 */
public function suspended(): Factory
{
    return $this->state(function (array $attributes) {
        return [
            'account_status' => 'suspended',
        ];
    });
}

"Trashed" 상태 (소프트 삭제)

Eloquent 모델이 소프트 삭제를 지원한다면, 내장된 trashed 상태 메서드를 호출해 생성된 모델을 소프트 삭제 상태로 만들 수 있습니다. 이 상태는 별도로 정의하지 않아도 모든 팩토리에서 자동으로 사용 가능합니다:

use App\Models\User;

$user = User::factory()->trashed()->create();

팩토리 콜백

팩토리 콜백은 afterMaking과 afterCreating 메서드로 등록하며, 모델 인스턴스 생성(make) 또는 데이터베이스 저장(create) 후 추가 작업이 필요할 때 사용합니다. 팩토리 클래스의 configure 메서드 안에서 등록하면 팩토리 인스턴스화 시 자동으로 호출됩니다:

namespace Database\Factories;

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

class UserFactory extends Factory
{
    /**
     * 모델 팩토리를 구성합니다.
     */
    public function configure(): static
    {
        return $this->afterMaking(function (User $user) {
            // 모델 인스턴스 생성 후 실행할 작업
        })->afterCreating(function (User $user) {
            // 데이터베이스에 저장 후 실행할 작업
        });
    }

    // ...
}

상태 메서드 내에서도 콜백을 등록할 수 있습니다. 이를 통해 특정 상태에서만 필요한 추가 작업을 처리할 수 있습니다:

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

/**
 * 사용자가 정지(suspended) 상태임을 나타냅니다.
 */
public function suspended(): Factory
{
    return $this->state(function (array $attributes) {
        return [
            'account_status' => 'suspended',
        ];
    })->afterMaking(function (User $user) {
        // 인스턴스 생성 후 추가 작업
    })->afterCreating(function (User $user) {
        // 저장 후 추가 작업
    });
}

팩토리로 모델 생성하기

모델 인스턴스화

팩토리를 정의한 뒤에는 HasFactory 트레이트가 제공하는 정적 factory 메서드로 팩토리 인스턴스를 만들고, 다양한 방법으로 모델을 생성할 수 있습니다. make 메서드는 데이터베이스에 저장하지 않고 모델 인스턴스만 반환합니다:

use App\Models\User;

$user = User::factory()->make();

count 메서드를 사용하면 여러 개의 모델을 컬렉션으로 만들 수 있습니다:

$users = User::factory()->count(3)->make();

상태 적용

상태 메서드는 체이닝해서 여러 개를 동시에 적용할 수 있습니다:

$users = User::factory()->count(5)->suspended()->make();

속성 재정의

특정 속성값만 기본값과 다르게 설정하고 싶다면, make 메서드에 배열을 전달하면 됩니다. 지정한 속성만 교체되고, 나머지는 팩토리의 기본값이 유지됩니다:

$user = User::factory()->make([
    'name' => '홍길동',
]);

팩토리 인스턴스에서 직접 state 메서드를 호출하는 방법도 있습니다:

$user = User::factory()->state([
    'name' => '홍길동',
])->make();

NOTE

팩토리로 모델을 생성할 때는 대량 할당 보호가 자동으로 비활성화됩니다.

모델 저장(영속화)

create 메서드는 모델 인스턴스를 생성하고, Eloquent의 save 메서드를 통해 데이터베이스에 실제로 저장합니다:

use App\Models\User;

// 단일 User 인스턴스 생성 및 저장
$user = User::factory()->create();

// 세 개의 User 인스턴스 생성 및 저장
$users = User::factory()->count(3)->create();

create 메서드에 배열을 전달해 기본 속성을 재정의할 수도 있습니다:

$user = User::factory()->create([
    'name' => '김철수',
]);

시퀀스(Sequence)

여러 모델을 생성할 때 특정 속성값을 교대로 변경하고 싶다면 Sequence를 사용하면 됩니다. 예를 들어 admin 컬럼 값을 Y와 N으로 번갈아 설정하려면:

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Sequence;

$users = User::factory()
    ->count(10)
    ->state(new Sequence(
        ['admin' => 'Y'],
        ['admin' => 'N'],
    ))
    ->create();

이 예시에서는 admin 값이 Y인 사용자 5명, N인 사용자 5명이 생성됩니다.

시퀀스 값으로 클로저를 사용할 수도 있습니다. 클로저는 새 값이 필요할 때마다 호출됩니다:

use Illuminate\Database\Eloquent\Factories\Sequence;

$users = User::factory()
    ->count(10)
    ->state(new Sequence(
        fn (Sequence $sequence) => ['role' => UserRoles::all()->random()],
    ))
    ->create();

클로저 내부에서는 주입된 $sequence 인스턴스의 $index 프로퍼티로 현재 반복 횟수(0부터 시작)를 확인할 수 있습니다:

$users = User::factory()
    ->count(10)
    ->state(new Sequence(
        fn (Sequence $sequence) => ['name' => '사용자 ' . $sequence->index],
    ))
    ->create();

편의를 위해 sequence 메서드를 사용할 수도 있습니다. 이 메서드는 내부적으로 state를 호출하며, 클로저나 속성 배열을 인자로 받습니다:

$users = User::factory()
    ->count(2)
    ->sequence(
        ['name' => '첫 번째 사용자'],
        ['name' => '두 번째 사용자'],
    )
    ->create();

팩토리 관계(Relationships)

Has Many 관계

팩토리의 플루언트(fluent) 메서드를 이용해 모델 간 관계도 손쉽게 구성할 수 있습니다. User 모델이 Post 모델과 hasMany 관계를 가진다고 가정하면, has 메서드를 사용해 3개의 포스트를 가진 사용자를 한 번에 생성할 수 있습니다:

use App\Models\Post;
use App\Models\User;

$user = User::factory()
    ->has(Post::factory()->count(3))
    ->create();

Laravel은 규칙에 따라 Post 모델을 has에 전달하면 User 모델의 posts 메서드를 관계로 사용합니다. 관계 메서드명을 명시적으로 지정하려면 두 번째 인자로 전달하세요:

$user = User::factory()
    ->has(Post::factory()->count(3), 'posts')
    ->create();

연관 모델에 상태 변경을 적용할 수도 있으며, 부모 모델에 접근이 필요한 경우 클로저 기반 상태를 사용할 수 있습니다:

$user = User::factory()
    ->has(
        Post::factory()
            ->count(3)
            ->state(function (array $attributes, User $user) {
                return ['user_type' => $user->type];
            })
    )
    ->create();

매직 메서드 사용

관계 생성을 더 간결하게 표현하려면 Laravel의 매직 메서드를 사용할 수 있습니다. 아래 예시는 User 모델의 posts 관계를 통해 포스트 3개를 생성합니다:

$user = User::factory()
    ->hasPosts(3)
    ->create();

매직 메서드에 배열을 전달해 연관 모델의 속성을 재정의할 수도 있습니다:

$user = User::factory()
    ->hasPosts(3, [
        'published' => false,
    ])
    ->create();

부모 모델에 접근이 필요한 경우 클로저를 전달합니다:

$user = User::factory()
    ->hasPosts(3, function (array $attributes, User $user) {
        return ['user_type' => $user->type];
    })
    ->create();

Belongs To 관계

has의 반대 방향인 역관계는 for 메서드로 정의합니다. 예를 들어, 특정 사용자에 속하는 포스트 3개를 생성하려면:

use App\Models\Post;
use App\Models\User;

$posts = Post::factory()
    ->count(3)
    ->for(User::factory()->state([
        'name' => '김영희',
    ]))
    ->create();

이미 생성된 부모 모델 인스턴스가 있다면 해당 인스턴스를 직접 for에 전달할 수 있습니다:

$user = User::factory()->create();

$posts = Post::factory()
    ->count(3)
    ->for($user)
    ->create();

매직 메서드 사용

Belongs To 관계도 매직 메서드로 간결하게 표현할 수 있습니다. 아래 예시는 Post 모델의 user 관계를 사용합니다:

$posts = Post::factory()
    ->count(3)
    ->forUser([
        'name' => '김영희',
    ])
    ->create();

다대다(Many to Many) 관계

Has Many 관계와 마찬가지로 다대다 관계도 has 메서드로 생성할 수 있습니다:

use App\Models\Role;
use App\Models\User;

$user = User::factory()
    ->has(Role::factory()->count(3))
    ->create();

피벗 테이블 속성

중간 테이블(피벗 테이블)에 속성을 설정해야 한다면 hasAttached 메서드를 사용합니다. 두 번째 인자로 피벗 테이블의 속성 배열을 전달합니다:

use App\Models\Role;
use App\Models\User;

$user = User::factory()
    ->hasAttached(
        Role::factory()->count(3),
        ['active' => true]
    )
    ->create();

연관 모델에 접근이 필요한 상태 변경은 클로저로 처리할 수 있습니다:

$user = User::factory()
    ->hasAttached(
        Role::factory()
            ->count(3)
            ->state(function (array $attributes, User $user) {
                return ['name' => $user->name . ' 역할'];
            }),
        ['active' => true]
    )
    ->create();

이미 생성된 모델 인스턴스를 연결할 때도 hasAttached를 사용합니다. 아래 예시에서는 동일한 3개의 역할이 3명의 사용자 모두에 연결됩니다:

$roles = Role::factory()->count(3)->create();

$users = User::factory()
    ->count(3)
    ->hasAttached($roles, ['active' => true])
    ->create();

매직 메서드 사용

다대다 관계도 매직 메서드로 간결하게 표현할 수 있습니다. 아래 예시는 User 모델의 roles 관계를 사용합니다:

$user = User::factory()
    ->hasRoles(1, [
        'name' => 'Editor'
    ])
    ->create();

다형성(Polymorphic) 관계

다형성 관계도 팩토리로 생성할 수 있습니다. "morph many" 관계는 일반 "has many" 관계와 동일한 방식으로 생성합니다. 예를 들어 Post 모델이 Comment 모델과 morphMany 관계라면:

use App\Models\Post;

$post = Post::factory()->hasComments(3)->create();

Morph To 관계

morphTo 관계는 매직 메서드를 사용할 수 없습니다. for 메서드를 직접 사용하고, 관계명을 명시해야 합니다. 예를 들어 Comment 모델에 commentable이라는 morphTo 관계가 있다면:

$comments = Comment::factory()->count(3)->for(
    Post::factory(), 'commentable'
)->create();

다형성 다대다 관계

다형성 다대다(morphToMany / morphedByMany) 관계는 일반 다대다 관계와 동일하게 생성합니다:

use App\Models\Tag;
use App\Models\Video;

$video = Video::factory()
    ->hasAttached(
        Tag::factory()->count(3),
        ['public' => true]
    )
    ->create();

물론 매직 has 메서드도 사용할 수 있습니다:

$video = Video::factory()
    ->hasTags(3, ['public' => true])
    ->create();

팩토리 내부에서 관계 정의하기

팩토리 안에서 관계를 정의하려면, 외래 키에 새 팩토리 인스턴스를 할당하면 됩니다. 이 방식은 주로 belongsTo, morphTo 같은 역관계에 사용합니다. 예를 들어 포스트 생성 시 새 사용자도 함께 생성하려면:

use App\Models\User;

/**
 * 모델의 기본 상태를 정의합니다.
 *
 * @return array<string, mixed>
 */
public function definition(): array
{
    return [
        'user_id' => User::factory(),
        'title' => fake()->title(),
        'content' => fake()->paragraph(),
    ];
}

관계 컬럼이 팩토리에서 생성된 다른 속성에 의존한다면, 클로저를 속성값으로 할당할 수 있습니다. 클로저는 팩토리의 평가된 속성 배열을 인자로 받습니다:

/**
 * 모델의 기본 상태를 정의합니다.
 *
 * @return array<string, mixed>
 */
public function definition(): array
{
    return [
        'user_id' => User::factory(),
        'user_type' => function (array $attributes) {
            return User::find($attributes['user_id'])->type;
        },
        'title' => fake()->title(),
        'content' => fake()->paragraph(),
    ];
}

기존 모델 재활용하기

여러 관계에서 동일한 모델 인스턴스를 공유해야 하는 경우, recycle 메서드를 사용하면 팩토리가 해당 타입의 모델이 필요할 때 새로 생성하지 않고 지정된 인스턴스를 재활용합니다.

예를 들어 Airline, Flight, Ticket 모델이 있고, 티켓은 항공사와 항공편에 속하며, 항공편도 항공사에 속하는 구조라고 가정합니다. 티켓과 항공편이 동일한 항공사를 사용하도록 보장하려면:

Ticket::factory()
    ->recycle(Airline::factory()->create())
    ->create();

동일한 사용자나 팀에 속하는 여러 모델을 생성할 때 recycle이 특히 유용합니다.

recycle 메서드에는 모델 컬렉션을 전달할 수도 있습니다. 컬렉션을 전달하면, 팩토리가 해당 타입의 모델이 필요할 때마다 컬렉션에서 랜덤으로 하나를 선택합니다:

Ticket::factory()
    ->recycle($airlines)
    ->create();