99

I know using:

User::firstOrCreate(array('name' => $input['name'], 'email' => $input['email'], 'password' => $input['password']));

Checks whether the user exists first, if not it creates it, but how does it check? Does it check on all the params provided or is there a way to specifiy a specific param, e.g. can I just check that the email address exists, and not the name - as two users may have the same name but their email address needs to be unique.

5 Answers 5

181

firstOrCreate() checks for all the arguments to be present before it finds a match. If not all arguments match, then a new instance of the model will be created.

If you only want to check on a specific field, then use firstOrCreate(['field_name' => 'value']) with only one item in the array. This will return the first item that matches, or create a new one if not matches are found.

The difference between firstOrCreate() and firstOrNew():

  • firstOrCreate() will automatically create a new entry in the database if there is not match found. Otherwise it will give you the matched item.
  • firstOrNew() will give you a new model instance to work with if not match was found, but will only be saved to the database when you explicitly do so (calling save() on the model). Otherwise it will give you the matched item.

Choosing between one or the other depends on what you want to do. If you want to modify the model instance before it is saved for the first time (e.g. setting a name or some mandatory field), you should use firstOrNew(). If you can just use the arguments to immediately create a new model instance in the database without modifying it, you can use firstOrCreate().

13
  • I know. How can I specify to match on specific attributes. I only want to check on email and then if that matches update, if not create a new record.
    – panthro
    Commented Aug 7, 2014 at 13:43
  • Thanks, I've done: $user = User::firstOrNew(array('email' => Input::get('email'))); $user->name = Input::get('name'); $user->save(); Correct?
    – panthro
    Commented Aug 7, 2014 at 13:47
  • I changed it to firstOrNew, or should I have used firstOrCreate?
    – panthro
    Commented Aug 7, 2014 at 13:47
  • You can do it in one step: $user = User::firstOrCreate(array('email' => Input::get('email'), 'name' => Input::get('name'))).
    – lowerends
    Commented Aug 7, 2014 at 13:49
  • You can't do it all in one step. If a new user has the same email BUT a different name, it will create a new record (it should update it as email is unique). Hence why I can't do mass assignment. Unless you know of a fix?
    – panthro
    Commented Aug 7, 2014 at 13:53
95

As of Laravel 5.3 it's possible to do this in one step with firstOrCreate using a second optional values parameter used only if a new record is created, and not for the initial search. It's explained in the documentation as follows:

The firstOrCreate method will attempt to locate a database record using the given column / value pairs. If the model cannot be found in the database, a record will be inserted with the attributes resulting from merging the first array argument with the optional second array argument.

Example

$user = User::firstOrCreate([
    'email' => '[email protected]'
], [
    'firstName' => 'Taylor',
    'lastName' => 'Otwell'
]);

This returns the User for the specified email if found, otherwise creates and returns a new user with the combined array of email, firstName, and lastName.


This technique requires Mass Assignment to be set up, either using the fillable or guarded properties to dictate which fields may be passed into the create call.

For this example the following would work (as a property of the User class):

/**
* The attributes that are mass assignable.
*
* @var array
*/
protected $fillable = ['email', 'firstName', 'lastName'];
3
  • 31
    I feel it's important to mention that the fields you want committed to the database need to be added to protected $fillable on the corresponding model since it uses mass assignment.
    – WhyAyala
    Commented Feb 6, 2018 at 22:23
  • WhyAyala notice is very important. Cause if you include in protected $fillable = ['email']; just keys from the first method firstOrCreate parameter your query would be like -> INSERT into tablename ('email', updated_at, created_at) VALUES...
    – darjus
    Commented Jul 20, 2018 at 7:29
  • Thanks for this clear and direct answer! By the way, it should be written "to be set up" as separate words. "Setup" is only joined when used as an adjective (to describe the word that comes after it), or as a noun (a thing, e.g. "here is your new setup"). Please help bring back correct word joinery and visual reading!
    – GeneC
    Commented Jul 20, 2021 at 19:35
5

firstOrCreate() checks for all the arguments to be present before it finds a match.

If you only want to check on a specific field, then use firstOrCreate(['field_name' => 'value']) like:

$user = User::firstOrCreate([
    'email' => '[email protected]'
], [
    'firstName' => 'abcd',
    'lastName' => 'efgh',
    'veristyName'=>'xyz',
]);

Then it checks only the email.

5

You can always check if in current instance the record is created with the help of

$user->wasRecentlyCreated

So basically you can

if($user->wasRecentlyCreated){

 // do what you need to do here

}
4

An update:

As of Laravel 5.3 doing this in a single step is possible; the firstOrCreate method now accepts an optional second array as an argument.

The first array argument is the array on which the fields/values are matched, and the second array is the additional fields to use in the creation of the model if no match is found via matching the fields/values in the first array:

See the Laravel API documentation

1
  • 1
    Great complementary info. Could be made as a comment, not per se an answer ; )
    – hugomosh
    Commented Aug 17, 2018 at 19:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.