Фабрики — Laravel

Під час тестування застосунку або наповнення бази даних вам може знадобитися вставити кілька записів у базу. Замість того щоб вручну вказувати значення кожної колонки, 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),
        ];
    }

    /**
     * Вказує, що email-адреса моделі має бути непідтвердженою.
     */
    public function unverified(): static
    {
        return $this->state(fn (array $attributes) => [
            'email_verified_at' => null,
        ]);
    }
}

Як бачите, у найпростішому вигляді фабрики — це класи, які розширюють базовий клас фабрики Laravel і визначають метод definition. Метод definition повертає типовий набір значень атрибутів, які мають застосовуватися під час створення моделі за допомогою фабрики.

Через хелпер fake фабрики мають доступ до PHP-бібліотеки Faker, яка дозволяє зручно генерувати різні види випадкових даних для тестування й наповнення бази.

Примітка Ви можете змінити локаль Faker у вашому застосунку, оновивши опцію faker_locale у конфігураційному файлі config/app.php.

Визначення фабрик моделей

Генерування фабрик

Щоб створити фабрику, виконайте Artisan-команду make:factory:

php artisan make:factory PostFactory

Новий клас фабрики буде розміщено в теці database/factories.

Домовленості про пошук моделі та фабрики

Після того як ви визначили свої фабрики, ви можете скористатися статичним методом factory, який надається вашим моделям трейтом Illuminate\Database\Eloquent\Factories\HasFactory, щоб створити екземпляр фабрики для цієї моделі.

Метод factory трейта HasFactory використовує домовленості, щоб визначити відповідну фабрику для моделі, якій призначено трейт. Зокрема, метод шукатиме фабрику в просторі імен Database\Factories з назвою класу, що відповідає назві моделі й має суфікс Factory. Якщо ці домовленості не підходять для вашого конкретного застосунку чи фабрики, ви можете додати до моделі атрибут UseFactory, щоб вручну вказати фабрику моделі:

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();
}

Потім використайте атрибут UseModel у відповідній фабриці, щоб вказати модель:

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

#[UseModel(Flight::class)]
class FlightFactory extends Factory
{
    // ...
}

Стани фабрики

Методи маніпуляції станом дозволяють визначати окремі модифікації, які можна застосовувати до фабрик моделей у будь-якій комбінації. Наприклад, ваша фабрика Database\Factories\UserFactory може містити метод стану suspended, який змінює одне з типових значень атрибутів.

Методи трансформації стану зазвичай викликають метод state, який надає базовий клас фабрики Laravel. Метод state приймає замикання, яке отримає масив «сирих» атрибутів, визначених для фабрики, і має повернути масив атрибутів для зміни:

use Illuminate\Database\Eloquent\Factories\Factory;

/**
 * Вказує, що користувача призупинено.
 */
public function suspended(): Factory
{
    return $this->state(function (array $attributes) {
        return [
            'account_status' => 'suspended',
        ];
    });
}

Стан «Trashed»

Якщо ваша модель Eloquent підтримує мʼяке видалення, ви можете викликати вбудований метод стану trashed, щоб вказати, що створена модель має бути вже «мʼяко видаленою». Вам не потрібно вручну визначати стан trashed, оскільки він автоматично доступний усім фабрикам:

use App\Models\User;

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

Колбеки фабрики

Колбеки фабрики реєструються за допомогою методів afterMaking та afterCreating і дозволяють виконувати додаткові завдання після створення (making) або збереження (creating) моделі. Реєструвати ці колбеки слід у методі configure вашого класу фабрики. Цей метод буде автоматично викликано Laravel під час створення екземпляра фабрики:

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;

/**
 * Вказує, що користувача призупинено.
 */
public function suspended(): Factory
{
    return $this->state(function (array $attributes) {
        return [
            'account_status' => 'suspended',
        ];
    })->afterMaking(function (User $user) {
        // ...
    })->afterCreating(function (User $user) {
        // ...
    });
}

Створення моделей за допомогою фабрик

Створення екземплярів моделей

Після того як ви визначили свої фабрики, ви можете скористатися статичним методом factory, який надається вашим моделям трейтом Illuminate\Database\Eloquent\Factories\HasFactory, щоб створити екземпляр фабрики для цієї моделі. Розгляньмо кілька прикладів створення моделей. Спершу скористаємося методом 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' => 'Abigail Otwell',
]);

Крім того, метод state можна викликати напряму на екземплярі фабрики, щоб виконати вбудовану (inline) трансформацію стану:

$user = User::factory()->state([
    'name' => 'Abigail Otwell',
])->make();

Примітка Захист від масового присвоєння автоматично вимикається під час створення моделей за допомогою фабрик.

Збереження моделей

Метод create створює екземпляри моделей і зберігає їх у базі даних за допомогою методу save Eloquent:

use App\Models\User;

// Створити один екземпляр App\Models\User...
$user = User::factory()->create();

// Створити три екземпляри App\Models\User...
$users = User::factory()->count(3)->create();

Ви можете перевизначити типові атрибути моделі у фабриці, передавши масив атрибутів у метод create:

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

Послідовності

Іноді вам може знадобитися чергувати значення певного атрибута моделі для кожної створеної моделі. Цього можна досягти, визначивши трансформацію стану як послідовність. Наприклад, ви можете захотіти чергувати значення колонки 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, і пʼятьох користувачів зі значенням admin, рівним N.

За потреби ви можете вказати як значення послідовності замикання. Замикання викликатиметься щоразу, коли послідовності потрібне нове значення:

use Illuminate\Database\Eloquent\Factories\Sequence;

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

Усередині замикання послідовності ви маєте доступ до властивості $index екземпляра послідовності, який впроваджується в замикання. Властивість $index містить кількість ітерацій послідовності, які відбулися на цей момент:

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

Для зручності послідовності також можна застосовувати за допомогою методу sequence, який усередині просто викликає метод state. Метод sequence приймає замикання або масиви атрибутів послідовності:

$users = User::factory()
    ->count(2)
    ->sequence(
        ['name' => 'First User'],
        ['name' => 'Second User'],
    )
    ->create();

Звʼязки у фабриках

Звʼязки «має багато»

Далі розгляньмо побудову звʼязків моделей Eloquent за допомогою плавних (fluent) методів фабрик Laravel. Спершу припустімо, що наш застосунок має моделі App\Models\User і App\Models\Post. Також припустімо, що модель User визначає звʼязок hasMany з Post. Ми можемо створити користувача, який має три пости, за допомогою методу has, який надають фабрики Laravel. Метод has приймає екземпляр фабрики:

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

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

За домовленістю, коли ви передаєте модель Post у метод has, Laravel припускає, що модель 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 для побудови звʼязків. Наприклад, наступний приклад за домовленістю визначить, що повʼязані моделі слід створити через метод звʼязку posts у моделі User:

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

Коли ви використовуєте магічні методи для створення звʼязків фабрик, ви можете передати масив атрибутів, які потрібно перевизначити у повʼязаних моделях:

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

Ви також можете передати кілька масивів атрибутів, щоб створити повʼязані моделі з окремим станом для кожної. Laravel застосує кожен масив по черзі:

$user = User::factory()
    ->hasPosts(
        ['title' => 'First Post'],
        ['title' => 'Second Post'],
        ['title' => 'Third Post'],
    )
    ->create();

Ви можете вказати трансформацію стану на основі замикання, якщо ваша зміна стану потребує доступу до батьківської моделі:

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

Звʼязки «належить до»

Тепер, коли ми розглянули побудову звʼязків «має багато» за допомогою фабрик, розгляньмо зворотний бік звʼязку. Метод for можна використовувати, щоб визначити батьківську модель, якій належать моделі, створені фабрикою. Наприклад, ми можемо створити три екземпляри моделі App\Models\Post, які належать одному користувачеві:

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

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

Якщо у вас уже є екземпляр батьківської моделі, який слід повʼязати зі створюваними моделями, ви можете передати екземпляр моделі в метод for:

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

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

Використання магічних методів

Для зручності ви можете використовувати магічні методи звʼязків фабрик Laravel, щоб визначати звʼязки «належить до». Наприклад, наступний приклад за домовленістю визначить, що три пости мають належати звʼязку user у моделі Post:

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

Звʼязки «багато до багатьох»

Як і звʼязки «має багато», звʼязки «багато до багатьох» можна створювати за допомогою методу has:

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

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

Атрибути проміжної таблиці

Якщо вам потрібно визначити атрибути, які слід встановити у pivot / проміжній таблиці, що звʼязує моделі, ви можете скористатися методом 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.' Role'];
            }),
        ['active' => true]
    )
    ->create();

Ви також можете передати масив pivot-масивів, щоб надати унікальні pivot-дані для кожної повʼязаної моделі:

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

Якщо у вас уже є екземпляри моделей, які ви хочете приєднати до створюваних моделей, ви можете передати ці екземпляри в метод hasAttached. У цьому прикладі одні й ті самі три ролі буде приєднано до всіх трьох користувачів:

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

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

Використання магічних методів

Для зручності ви можете використовувати магічні методи звʼязків фабрик Laravel, щоб визначати звʼязки «багато до багатьох». Наприклад, наступний приклад за домовленістю визначить, що повʼязані моделі слід створити через метод звʼязку roles у моделі User:

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

Поліморфні звʼязки

Поліморфні звʼязки також можна створювати за допомогою фабрик. Поліморфні звʼязки «morph many» створюються так само, як звичайні звʼязки «має багато». Наприклад, якщо модель App\Models\Post має звʼязок morphMany з моделлю App\Models\Comment:

use App\Models\Post;

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

Звʼязки «Morph To»

Магічні методи не можна використовувати для створення звʼязків morphTo. Натомість потрібно використовувати метод for напряму й явно вказувати назву звʼязку. Наприклад, уявіть, що модель Comment має метод commentable, який визначає звʼязок morphTo. У цій ситуації ми можемо створити три коментарі, які належать одному посту, використовуючи метод for напряму:

$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, де квиток належить авіакомпанії та рейсу, а рейс також належить авіакомпанії. Створюючи квитки, ви, ймовірно, захочете, щоб і для квитка, і для рейсу була та сама авіакомпанія, тож ви можете передати екземпляр авіакомпанії в метод recycle:

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

Метод recycle може бути особливо корисним, якщо у вас є моделі, що належать спільному користувачеві чи команді.

Метод recycle також приймає колекцію наявних моделей. Коли в метод recycle передано колекцію, з неї буде обрано випадкову модель, коли фабриці знадобиться модель цього типу:

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