What are the available options for Eloquent's Model::save() method?

Question

Eloquent has a method called save(), which takes an optional array of parameters (options). However, the API reference doesn't seem to explain what these options are.

Is there a list somewhere that I'm missing? I could track them down through the source code of course (I see touch and timestamp, at least), but I figured at the very least this question would be useful as a reference to others.

Answer 1

tl;dr

In the $options array you can disable timestamping for that specific query:

$item->save([
    'timestamps' => false, // Disable timestamping on insert and update.
    'touch'      => false, // Disable parent timestamping.
]);

See: Eloquent Model Conventions: Timestamps and Touching Parent Timestamps.
Note: Since 5.3 the timestamps option is no longer supported.

Full review

If you take a look at the source code you can see, that in the save() method, the $options variable is passed to three functions:

• timestamps support is provided by performInsert() and performUpdate().
• touch support is provided by finishSave().

The timestamps option

Both performInsert() and performUpdate() will check the timestamps key in the $options array in conjuction with the $timestamps property of the model:

if ($this->timestamps && Arr::get($options, 'timestamps', true))

If this expression is true, it will touch the timestamps.

Because of the fact that $option['timestamps'] defaults to true and it is in conjuction with the model property, the only use of this option (when it makes a difference) is when timestamping is enabled in the model but you want to disable it on a particular query. You can't do the opposite: enable timestamping while it is disabled in the model - which might be counterintuitive.

Note: Since 5.3 the performInsert() and performUpdate() functions doesn't work with the values in the $options parameter.

The touch option

If this option is set to false, it will disable the touch of the parent relationships set in the model's $touches property. This option defaults to true so just like the timestamps option it is only for disabling timestamping for that particular query.