Update push and pull docs

[hans-thomas]

Fixes #2387,
Hello there, I updated the push and pull methods documentation to solve the confusion about using these methods.

[GromNaN]

I like this improvement. It's a good step for more clarity.

[jmikola]

I haven't checked the code, but this suggests that the boolean causes $addToSet to be used internally instead of $push. Is that correct?

Having a boolean argument control that rubs me the wrong way (I'll add it to the growing list), but I assume there's an explanation for this behavior. Is the push() method here actually derived from something else in Eloquent, or was it originally created in this library specifically for the MQL operators?

[hans-thomas]

I haven't checked the code, but this suggests that the boolean causes $addToSet to be used internally instead of $push. Is that correct?

Yes. It's the logged queries of pushing normally and pushing unique values.

array:2 [
  0 => array:3 [
    "query" => "users.updateMany({"_id":"65672f58551357588a07c993"},{"$push":{"items":{"$each":["boots"]}}},{"multiple":true})"
    "bindings" => []
    "time" => 1.82
  ]
  1 => array:3 [
    "query" => "users.updateMany({"_id":"65672f58551357588a07c993"},{"$addToSet":{"items":{"$each":["hat","jeans"]}}},{"multiple":true})"
    "bindings" => []
    "time" => 0.6
  ]
]

Having a boolean argument control that rubs me the wrong way (I'll add it to the growing list), but I assume there's an explanation for this behavior. Is the push() method here actually derived from something else in Eloquent, or was it originally created in this library specifically for the MQL operators?

The push method is originally from Eloquent and it's used for saving a model instance and its relationships to the database. this library overrides the push method and accepts three args. If no arg is passed, the original push method will be called.

[jmikola]

Is Eloquent's push method documented anywhere beyond Recursively Saving Models & Relationships? That doesn't appear to take any arguments and the method seems entirely different in purpose (this doesn't have to do with relationships).

@GromNaN: A boolean flag to determine whether $push or $addToSet is used seems like a poor design as it makes the code less self-documenting. I think this is compounded by the fact that the method on the model class uses func_get_args() and doesn't define a named parameter that users could specify if they so desired.

It may be worth making a ticket to revisit this down the line. Perhaps introduce a new addToSet() method and then deprecate the original variation. This might also be a moot point when/if the query builder is integrated.

[GromNaN]

💯 agree that the double behavior of this method is a bad design.

If deprecate the custom behavior of Model::push with parameters, we have to do deprecate the pull method too.

Let's improve the documentation for now.

[jmikola]

LGTM, so over to @GromNaN.

[GromNaN]

Thank you @hans-thomas for the care taken with the documentation and for your kind review @jmikola