Skip to content

Update push and pull docs #2685

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Merged
merged 13 commits into from
Dec 4, 2023
Merged

Update push and pull docs #2685

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
18701c9
Update push documentation;
hans-thomas Nov 23, 2023
36323f3
WIP
hans-thomas Nov 23, 2023
7fd5a6a
Update pull documentation;
hans-thomas Nov 23, 2023
19330c5
WIP
hans-thomas Nov 23, 2023
9ba44df
WIP
hans-thomas Nov 23, 2023
d47380c
WIP
hans-thomas Nov 23, 2023
ac3d9ab
Notice added for value arrays;
hans-thomas Nov 25, 2023
010663f
Update push docs;
hans-thomas Nov 25, 2023
c2bd491
Update pull docs;
hans-thomas Nov 25, 2023
7cb4def
Fix the JS syntax;
hans-thomas Nov 25, 2023
982d724
Update docs;
hans-thomas Nov 29, 2023
509b009
Update query-builder.md
hans-thomas Dec 2, 2023
a55fc86
Merge branch '4.1' into 2387-update-docs
GromNaN Dec 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 97 additions & 25 deletions docs/query-builder.md
View file
Original file line number Diff line number Diff line change
@@ -448,64 +448,136 @@ DB::collection('items')

**Push**

Add items to an array.
Add one or multiple values to the `items` array.

```php
// Push the value to the matched documents
DB::collection('users')
->where('name', 'John')
->push('items', 'boots');
->where('name', 'John')
// Push a single value to the items array
->push('items', 'boots');
// Result:
// items: ['boots']

DB::collection('users')
->where('name', 'John')
// Push multiple values to the items array
->push('items', ['hat', 'jeans']);
// Result:
// items: ['boots', 'hat', 'jeans']

// Or

// Push the values directly to a model object
$user->push('items', 'boots');
$user->push('items', ['hat', 'jeans']);
```

To add embedded document or array values to the `messages` array, those values must be specified within a list array.

```php
DB::collection('users')
->where('name', 'John')
->push('messages', [
'from' => 'Jane Doe',
'message' => 'Hi John',
]);
->where('name', 'John')
// Push an embedded document as a value to the messages array
->push('messages', [
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ]
]);
// Result:
// messages: [
// { from: "Jane Doe", message: "Hi John" }
// ]

// Or

$user->push('messages', [
'from' => 'Jane Doe',
'message' => 'Hi John',
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ]
]);
```

If you **DON'T** want duplicate items, set the third parameter to `true`:
If you **DON'T** want duplicate values, set the third parameter to `true`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

@hans-thomas hans-thomas Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@jmikola jmikola Nov 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯 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.


```php
DB::collection('users')
->where('name', 'John')
->push('items', 'boots', true);
->where('name', 'John')
->push('items', 'boots');
// Result:
// items: ['boots']

DB::collection('users')
->where('name', 'John')
->push('items', ['hat', 'boots', 'jeans'], true);
// Result:
// items: ['boots', 'hat', 'jeans']

// Or

$user->push('items', 'boots', true);
$user->push('messages', [
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ]
]);
// Result:
// messages: [
// { from: "Jane Doe", message: "Hi John" }
// ]

$user->push('messages', [
[ 'from' => 'Jess Doe', 'message' => 'Hi' ],
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ],
], true);
// Result:
// messages: [
// { from: "Jane Doe", message: "Hi John" }
// { from: "Jess Doe", message: "Hi" }
// ]
```

**Pull**

Remove an item from an array.
Remove one or multiple values from the `items` array.

```php
// items: ['boots', 'hat', 'jeans']

DB::collection('users')
->where('name', 'John')
->pull('items', 'boots');
->where('name', 'John')
->pull('items', 'boots'); // Pull a single value
// Result:
// items: ['hat', 'jeans']

$user->pull('items', 'boots');
// Or pull multiple values

$user->pull('items', ['boots', 'jeans']);
// Result:
// items: ['hat']
```

Embedded document and arrays values can also be removed from the `messages` array.

```php
// Latest state:
// messages: [
// { from: "Jane Doe", message: "Hi John" }
// { from: "Jess Doe", message: "Hi" }
// ]

DB::collection('users')
->where('name', 'John')
->pull('messages', [
'from' => 'Jane Doe',
'message' => 'Hi John',
]);
->where('name', 'John')
// Pull an embedded document from the array
->pull('messages', [
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ]
]);
// Result:
// messages: [
// { from: "Jess Doe", message: "Hi" }
// ]

// Or pull multiple embedded documents

$user->pull('messages', [
'from' => 'Jane Doe',
'message' => 'Hi John',
[ 'from' => 'Jane Doe', 'message' => 'Hi John' ],
[ 'from' => 'Jess Doe', 'message' => 'Hi' ]
]);
// Result:
// messages: [ ]
```

**Unset**