[12.x] Allowing merging model attributes before insert via Model::fillAndInsert()

[cosmastech]

I submitted a PR for this about two years ago, but I wanted to take a second shot at it.

---

The Goal

Be able to perform a bulk insert of records without having to manually cast values to primitives, set timestamps, or set UUIDs in an array_map(). Why is this important?

Inserting models one-by-one is terribly inefficient. The upsert() functionality already does quite a bit of the heavy lifting (setting timestamps and unique string IDs), but doesn't play nice with casts.

Current Way of Doing This

Write a custom macro. Since the last PR, I have added this to three separate projects, and will probably always add it to new projects where I need to be able to bulk insert records.

Loop through all of your records and add the casts/timestamps yourself. This works, but isn't easy to reach for.

Due to this headache, I believe it nudges users into performing inserts one-by-one, which will lead to increased DB load and performance degradations at scale. (We don't want people mistakenly thinking Laravel is slow)

How to use this functionality

ModelWithUniqueStringIds::fillAndInsert([
    [
        'name' => 'Taylor', 'role' => IntBackedRole::Admin, 'role_string' => StringBackedRole::Admin,
    ],
    [
        'name' => 'Nuno', 'role' => 3, 'role_string' => 'admin',
    ],
    [
        'name' => 'Dries', 'uuid' => 'bbbb0000-0000-7000-0000-000000000000',
    ],
    [
        'name' => 'Chris',
    ],
]);

This will convert the enums to their raw values, cast any objects/arrays to their DB representation, add created_at/updated_at timestamps, and set unique string IDs.

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[ezequidias]

Wouldn't it be better to use:

$albums = collect([
  Album::make([ 'genre' => Genre::Rock ...]),
  Album::make([ 'genre' => Genre::HipHop...]),
  Album::make([ 'genre' => Genre::Pop...]),
])->toArray();

Album::insert($albums);

[cosmastech]

Wouldn't it be better to use:

Album::insert([
  Album::make([ 'genre' => Genre::Rock ...]),
  Album::make([ 'genre' => Genre::HipHop...]),
  Album::make([ 'genre' => Genre::Pop...]),
]);

Great call! That's another thing I have considered. I may try to add that to this PR, or maybe we'll see if it gets accepted with less moving pieces to start. 🤔

[taylorotwell]

I do kind of wonder if some new method like that would be better than this opt-in way which feels very clunky imo. 🤔

[cosmastech]

I do kind of wonder if some new method like that would be better than this opt-in way which feels very clunky imo. 🤔

I agree on the clunkiness. My original version was insertWithCasts() but I really find that name equally clunky.

I'm open to any suggestions you may have @taylorotwell 🙇

[taylorotwell]

@cosmastech hmm yeah I'm not sure I have any suggestions, but imagine a new method like Model::bulk or something. Not that name probably but something like that I would prefer over this imo.

[cosmastech]

@cosmastech hmm yeah I'm not sure I have any suggestions, but imagine a new method like Model::bulk or something. Not that name probably but something like that I would prefer over this imo.

@taylorotwell after chatting with some other folks (namely Claude, Chat Gippity, and my manager), I went with hydrateAndInsert().

hydrate is a pretty Laravel friendly term (used in various places throughout the ecosystem, including on the Builder and model). The hope is that a user may be able guess what this function does based purely on the name.

Why hydrateAndInsert() instead of insertHydrated(): a user may mistakenly guess that this requires them to have hydrated the values before calling the methods.

[cosmastech]

thought: I believe we may want to allow creating these via collections as well. I could keep the docblock typehints and remove the parameter typehint here. Curious to know your thoughts.

[taylorotwell]

@cosmastech is there an issue with just calling the method createMany? Some Eloquent relationships already use this method name.

[cosmastech]

@cosmastech is there an issue with just calling the method createMany? Some Eloquent relationships already use this method name.

Hi @taylorotwell... I think that could be confusing given that the model's create() method returns a model instance, so the expectation would probably be that createMany() would create and return a collection of Models. The methods on relations for createMany() return collections of models.

I don't think it would break anything to change the name here, just concerned about presenting confusion.

[taylorotwell]

@cosmastech maybe insertMany then? 😅

[cosmastech]

@cosmastech maybe insertMany then? 😅

You're the boss, so I can make that change. However, I feel it's still perhaps confusing, since insert() already accepts a list of associative arrays, so it already inserts many.

Is there a word other than hydrate that touches on the function of this without feeling clumsy? What about insertAsModel?

Thank goodness this PR doesn't have anything to do with cache invalidation. Otherwise we'd be facing the two hardest problems in computer science simultaneously 😆

[taylorotwell]

@cosmastech maybe fillAndInsert. I think that keeps the consistent fill language we use already and is reflective of what is happening. Only downside is this is unguarded.

[cosmastech]

@cosmastech maybe fillAndInsert. I think that keeps the consistent fill language we use already and is reflective of what is happening. Only downside is this is unguarded.

@taylorotwell done.

While I think a fill* method does perhaps give a user the expectation that model fields are guarded... however, insert() is totally unguarded. So I think it's kind of a horse a piece.

[taylorotwell]

@cosmastech 🤝