Problem

Let's take a typical factory with a relationship. We'll use the example right off the Laravel docs.

$factory->define(App\Post::class, function ($faker) {
    return [
        'title' => $faker->title,
        'content' => $faker->paragraph,
        'user_id' => factory(App\User::class),
    ];
});

When we create a Post, we will also create a User. At the surface this seems okay, but let's think what happens when we create 50 Posts.

factory(Post::class, 50)->create();

Without the relationship we'd be running 50 inserts, but with the relationship we double that to 100 queries! Now imagine a factory that has multiple relationships. The number of database queries (and time) grows with each new relationship handled this way.

What if we assume that Users have already been created, and we'll randomly select 1 to attach the Post to?

$factory->define(App\Post::class, function ($faker) {
    return [
        'title' => $faker->title,
        'content' => $faker->paragraph,
        'user_id' => App\User::all()->random(),
    ];
});

Unfortunately, this does not cut down on our query count, since the all() query is executed for every single new Post.

We can also not pass it as an override attribute.

factory(Post::class, 50)->create([
    'user_id' => App\User::all()->random(),
]);

This will cut down our query count, but since it is only executed once, all 50 Posts will receive the same User ID, which is not what we want.

Solution

The solution to this is a feature I call "primers". At the time of building the factories, you can inject key/value pairs into the builder that the factories can then use to generate their data.

Let's first look at how we call it. Simply chain the prime() method onto your factory prior to calling make() or create(), and pass it a string key and a value of any type you like.

factory(Post::class, 50)->prime('users', User::all())->create();

With this call we've made 1 query to get all the Users. Now let's see how to use primers in the factories.

$factory->define(App\Post::class, function ($faker, $attributes, $primers) {
    return [
        'title' => $faker->title,
        'content' => $faker->paragraph,
        'user_id' => $primers['users'] ? $primers['users']->random() : factory(App\User::class),
    ];
});

Here we can see the primers are passed into the factory definition as a new 3rd parameter. For properties that we expect primers for, we should first check to see the primer exists. If the primer exists, we can use it as needed, but also fall back to the old way of determining the relationship if the primer was not provided.

With this new feature, and a primed factory, we've now cut our queries down from 100 to 51!

Primers can also be used with factory states.

$factory->state(App\Post::class, 'admin-posts', function ($faker, $attributes, $primers) {
    return [
        'user_id' => $primers['users'] ? $primers['users']->random() : factory(App\User::class),
    ];
});

factory(Post::class, 50)->state('admin-posts')->prime('users', User::where('type', 'admin')->get())->create();

Practical Usage

There are 2 primary places factories are used: tests and seeders.

In regards to Tests, let's assume we have Users, Posts, and Comments. Both Posts and Comments belong to a User that authored them.

Currently to test we may write something like:

public function test_posts()
{
    $posts = factory(Post::class, 10)->create();

    foreach($posts as $post) {
        factory(Comment::class, 5)->create([
            'post_id' => $post->id
        ]);
    }

    $this->get('/posts')
             ->makeAssertions();
}

Both the Post and Comment factory will be deferring to the factory to create new Users. Therefore, this test would run 120 queries. 10 to create the Posts, 50 to create the Comments, 10 to create the Post Users, and 50 to create the Comment Users.

Now let's tweak it just a little to improve our performance.

public function test_posts()
{
    $users = factory(User::class, 10)->create();

    $posts = factory(Post::class, 10)->prime('users', $users)->create();

    foreach($posts as $post) {
        factory(Comment::class, 5)->prime('users', $users)->create([
            'post_id' => $post->id
        ]);
    }

    $this->get('/posts')
             ->makeAssertions();
}

We're now down to 70 queries from 120!

In regards to seeding, we can make some small tweaks to our DatabaseSeeder to improve performance.

Currently you might do something like:

public function run()
{
    factory(User::class, 10)->create();
    factory(Post::class, 50)->create();
    factory(Comment::class, 50)->create();
}

Without primers this will require 210 queries.

Let use primers to improve this.

public function run()
{
    $users = factory(User::class, 10)->create();
    factory(Post::class, 50)->prime('users', $users)->create();
    factory(Comment::class, 50)->prime('users', $users)->create();
}

This takes us down to 110 queries, hooray!

Caveats

There is one thing to be aware of when using primers. It is very possible the factory could make assumptions about what type of data it is getting from the primer. My guess is the most common use case will be to pass Collections in.

$factory->define(App\Post::class, function ($faker, $attributes, $primers) {
    return [
        'title' => $faker->title,
        'content' => $faker->paragraph,
        'user_id' => $primers['users'] ? $primers['users']->random() : factory(App\User::class),
    ];
});

You can see if the primer exists we are calling random() on it. If the users passes in the incorrect type of data, it will cause an error.

factory(Post::class, 50)->prime('users', [1, 2, 3])->create();

Here you can see we passed an array instead of a Collection, so when the factory is run it will throw an error that random() does not exist.

This error will be easy enough to identify and correct, so I'm not really worried about it, but just something to be aware of.