From 18701c907f60f7557b8f0cdc30a0e78671b5a5b0 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 16:37:43 +0330 Subject: [PATCH 01/12] Update push documentation; --- docs/query-builder.md | 68 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 55 insertions(+), 13 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 9672e21ef..a22c368cd 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -448,27 +448,47 @@ DB::collection('items') **Push** -Add items to an array. +Add one or more 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'); // items: ['boots'] + +DB::collection('users') + ->where('name', 'John') + // Push multiple values to the items array + ->push('items', ['hat', 'jeans']); // items: ['boots', 'hat', 'jeans'] + +// Or +// Push the value to exact document $user->push('items', 'boots'); +$user->push('items', ['hat', 'jeans']); ``` +To add an array to the items array. + ```php DB::collection('users') - ->where('name', 'John') - ->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); + ->where('name', 'John') + // Push an array as a value to the items array + ->push('messages', [ + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ], + ]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ] + +// Or $user->push('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ], ]); ``` @@ -476,10 +496,32 @@ If you **DON'T** want duplicate items, set the third parameter to `true`: ```php DB::collection('users') - ->where('name', 'John') - ->push('items', 'boots', true); + ->where('name', 'John') + ->push('items', 'boots'); // items: ['boots'] -$user->push('items', 'boots', true); +DB::collection('users') + ->where('name', 'John') + ->push('items', ['hat', 'boots', 'jeans'], true); // items: ['boots', 'hat', 'jeans'] + +// Or + +$user->push('messages', [ + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ], +]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ] + +$user->push('messages', [ + [ + 'from' => 'Jess Doe', + 'message' => 'Hi John', + ], + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ], +], true); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ] ``` **Pull** From 36323f348fb95791b8822f535f7b16a98d999b70 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 16:46:42 +0330 Subject: [PATCH 02/12] WIP --- docs/query-builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index a22c368cd..a88877bb8 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -464,7 +464,7 @@ DB::collection('users') // Or -// Push the value to exact document +// Push the value to an exact document $user->push('items', 'boots'); $user->push('items', ['hat', 'jeans']); ``` From 7fd5a6a37bcc195a20502241a26408d9cfcf94e8 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 17:00:17 +0330 Subject: [PATCH 03/12] Update pull documentation; --- docs/query-builder.md | 44 +++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index a88877bb8..a779aff85 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -526,28 +526,48 @@ $user->push('messages', [ **Pull** -Remove an item from an array. +Remove a value form items array. ```php +// items: ['boots', 'hat', 'jeans'] + DB::collection('users') - ->where('name', 'John') - ->pull('items', 'boots'); + ->where('name', 'John') + // Pull a single value + ->pull('items', 'boots'); // items: ['hat', 'jeans'] -$user->pull('items', 'boots'); +// Or pull multiple values + +$user->pull('items', ['boots', 'jeans']); // items: ['hat'] ``` +Also, you can pull an array value from the items array. + ```php +// messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ] + DB::collection('users') - ->where('name', 'John') - ->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ]); + ->where('name', 'John') + // It will search for the exact array and pulls it + ->pull('messages', [ + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ] + ]); // messages: [ ['from' => 'Jess Doe', 'message' => 'Hi John'] ] + +// Or pull multiple array $user->pull('messages', [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', -]); + [ + 'from' => 'Jane Doe', + 'message' => 'Hi John', + ], + [ + 'from' => 'Jess Doe', + 'message' => 'Hi John', + ] +]); // messages: [ ] ``` **Unset** From 19330c5d8d83ab674e5eb6b6f81eb087dc356986 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 17:03:22 +0330 Subject: [PATCH 04/12] WIP --- docs/query-builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index a779aff85..b28779f8f 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -541,7 +541,7 @@ DB::collection('users') $user->pull('items', ['boots', 'jeans']); // items: ['hat'] ``` -Also, you can pull an array value from the items array. +Also, you can pull an array value from the messages array. ```php // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ] From 9ba44df8eeda45e481c38b09f665da4b1a9a934d Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 17:04:12 +0330 Subject: [PATCH 05/12] WIP --- docs/query-builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index b28779f8f..e1bb22431 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -469,7 +469,7 @@ $user->push('items', 'boots'); $user->push('items', ['hat', 'jeans']); ``` -To add an array to the items array. +To add an array to the messages array. ```php DB::collection('users') From d47380ccfb3cba967855191600847133726ceed3 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Thu, 23 Nov 2023 17:06:52 +0330 Subject: [PATCH 06/12] WIP --- docs/query-builder.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index e1bb22431..06a25968b 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -448,7 +448,7 @@ DB::collection('items') **Push** -Add one or more values to the items array. +Add one or multiple values to the items array. ```php // Push the value to the matched documents @@ -492,7 +492,7 @@ $user->push('messages', [ ]); ``` -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`: ```php DB::collection('users') @@ -526,7 +526,7 @@ $user->push('messages', [ **Pull** -Remove a value form items array. +Remove one or multiple values form items array. ```php // items: ['boots', 'hat', 'jeans'] From ac3d9ab3bbdbbdc3b52822164927d38e1f0da543 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Sat, 25 Nov 2023 14:30:59 +0330 Subject: [PATCH 07/12] Notice added for value arrays; --- docs/query-builder.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 06a25968b..6120ff0c8 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -469,7 +469,8 @@ $user->push('items', 'boots'); $user->push('items', ['hat', 'jeans']); ``` -To add an array to the messages array. +To add an array as a value to the messages array. value arrays must be nested into a list array, otherwise they are +interpreted as a list of scalar values. ```php DB::collection('users') From 010663f5de07a39ee3f104284c0cf5c19b8e0b94 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Sat, 25 Nov 2023 14:41:14 +0330 Subject: [PATCH 08/12] Update push docs; --- docs/query-builder.md | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 6120ff0c8..738451415 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -454,13 +454,17 @@ Add one or multiple values to the items array. // Push the value to the matched documents DB::collection('users') ->where('name', 'John') - // Push a single value to the items array - ->push('items', 'boots'); // items: ['boots'] + // 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']); // items: ['boots', 'hat', 'jeans'] + // Push multiple values to the items array + ->push('items', ['hat', 'jeans']); +// Result: +// items: ['boots', 'hat', 'jeans'] // Or @@ -481,7 +485,11 @@ DB::collection('users') 'from' => 'Jane Doe', 'message' => 'Hi John', ], - ]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ] + ]); +// Result: +// messages: [ +// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// ] // Or @@ -498,11 +506,15 @@ If you **DON'T** want duplicate values, set the third parameter to `true`: ```php DB::collection('users') ->where('name', 'John') - ->push('items', 'boots'); // items: ['boots'] + ->push('items', 'boots'); +// Result: +// items: ['boots'] DB::collection('users') ->where('name', 'John') - ->push('items', ['hat', 'boots', 'jeans'], true); // items: ['boots', 'hat', 'jeans'] + ->push('items', ['hat', 'boots', 'jeans'], true); +// Result: +// items: ['boots', 'hat', 'jeans'] // Or @@ -511,18 +523,27 @@ $user->push('messages', [ 'from' => 'Jane Doe', 'message' => 'Hi John', ], -]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ] +]); +// Result: +// messages: [ +// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// ] $user->push('messages', [ [ 'from' => 'Jess Doe', - 'message' => 'Hi John', + 'message' => 'Hi', ], [ 'from' => 'Jane Doe', 'message' => 'Hi John', ], -], true); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ] +], true); +// Result: +// messages: [ +// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// ] ``` **Pull** From c2bd4914291c2c99a515173d7de59ba2bae9df1e Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Sat, 25 Nov 2023 14:44:32 +0330 Subject: [PATCH 09/12] Update pull docs; --- docs/query-builder.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 738451415..92494b9c8 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -555,18 +555,25 @@ Remove one or multiple values form items array. DB::collection('users') ->where('name', 'John') - // Pull a single value - ->pull('items', 'boots'); // items: ['hat', 'jeans'] + ->pull('items', 'boots'); // Pull a single value +// Result: +// items: ['hat', 'jeans'] // Or pull multiple values -$user->pull('items', ['boots', 'jeans']); // items: ['hat'] +$user->pull('items', ['boots', 'jeans']); +// Result: +// items: ['hat'] ``` Also, you can pull an array value from the messages array. ```php -// messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ] +// Latest state: +// messages: [ +// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// ] DB::collection('users') ->where('name', 'John') @@ -576,7 +583,11 @@ DB::collection('users') 'from' => 'Jane Doe', 'message' => 'Hi John', ] - ]); // messages: [ ['from' => 'Jess Doe', 'message' => 'Hi John'] ] + ]); +// Result: +// messages: [ +// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// ] // Or pull multiple array @@ -587,9 +598,11 @@ $user->pull('messages', [ ], [ 'from' => 'Jess Doe', - 'message' => 'Hi John', + 'message' => 'Hi', ] -]); // messages: [ ] +]); +// Result: +// messages: [ ] ``` **Unset** From 7cb4deffa37ccfe47dde945198f81f00a02cd7f0 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Sat, 25 Nov 2023 15:21:01 +0330 Subject: [PATCH 10/12] Fix the JS syntax; --- docs/query-builder.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 92494b9c8..3d56eeadf 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -488,7 +488,7 @@ DB::collection('users') ]); // Result: // messages: [ -// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// { from: "Jane Doe", message: "Hi John" } // ] // Or @@ -526,7 +526,7 @@ $user->push('messages', [ ]); // Result: // messages: [ -// { 'from' => 'Jane Doe', 'message' => 'Hi John' } +// { from: "Jane Doe", message: "Hi John" } // ] $user->push('messages', [ @@ -541,8 +541,8 @@ $user->push('messages', [ ], true); // Result: // messages: [ -// { 'from' => 'Jane Doe', 'message' => 'Hi John' } -// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// { from: "Jane Doe", message: "Hi John" } +// { from: "Jess Doe", message: "Hi" } // ] ``` @@ -571,8 +571,8 @@ Also, you can pull an array value from the messages array. ```php // Latest state: // messages: [ -// { 'from' => 'Jane Doe', 'message' => 'Hi John' } -// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// { from: "Jane Doe", message: "Hi John" } +// { from: "Jess Doe", message: "Hi" } // ] DB::collection('users') @@ -586,7 +586,7 @@ DB::collection('users') ]); // Result: // messages: [ -// { 'from' => 'Jess Doe', 'message' => 'Hi' } +// { from: "Jess Doe", message: "Hi" } // ] // Or pull multiple array From 982d72445f8e2ab0100b2c1cf832051b64c752bf Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Wed, 29 Nov 2023 17:18:18 +0330 Subject: [PATCH 11/12] Update docs; Co-Authored-By: Jeremy Mikola --- docs/query-builder.md | 53 ++++++++++++------------------------------- 1 file changed, 14 insertions(+), 39 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 3d56eeadf..913b55e0e 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -448,7 +448,7 @@ DB::collection('items') **Push** -Add one or multiple values to the items array. +Add one or multiple values to the `items` array. ```php // Push the value to the matched documents @@ -468,23 +468,19 @@ DB::collection('users') // Or -// Push the value to an exact document +// Push the values directly to a model object $user->push('items', 'boots'); $user->push('items', ['hat', 'jeans']); ``` -To add an array as a value to the messages array. value arrays must be nested into a list array, otherwise they are -interpreted as a list of scalar values. +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 an array as a value to the items array + // Push an embedded document as a value to the messages array ->push('messages', [ - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); // Result: // messages: [ @@ -494,10 +490,7 @@ DB::collection('users') // Or $user->push('messages', [ - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); ``` @@ -519,10 +512,7 @@ DB::collection('users') // Or $user->push('messages', [ - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); // Result: // messages: [ @@ -530,14 +520,8 @@ $user->push('messages', [ // ] $user->push('messages', [ - [ - 'from' => 'Jess Doe', - 'message' => 'Hi', - ], - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ], + [ 'from' => 'Jess Doe', 'message' => 'Hi' ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], ], true); // Result: // messages: [ @@ -548,7 +532,7 @@ $user->push('messages', [ **Pull** -Remove one or multiple values form items array. +Remove one or multiple values from the `items` array. ```php // items: ['boots', 'hat', 'jeans'] @@ -566,7 +550,7 @@ $user->pull('items', ['boots', 'jeans']); // items: ['hat'] ``` -Also, you can pull an array value from the messages array. +Embedded document and arrays values can also be pulled from the `messages` array. ```php // Latest state: @@ -579,10 +563,7 @@ DB::collection('users') ->where('name', 'John') // It will search for the exact array and pulls it ->pull('messages', [ - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ] + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); // Result: // messages: [ @@ -592,14 +573,8 @@ DB::collection('users') // Or pull multiple array $user->pull('messages', [ - [ - 'from' => 'Jane Doe', - 'message' => 'Hi John', - ], - [ - 'from' => 'Jess Doe', - 'message' => 'Hi', - ] + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], + [ 'from' => 'Jess Doe', 'message' => 'Hi' ] ]); // Result: // messages: [ ] From 509b009a9f02c729a1a3368a7f04a9b30dcb56a9 Mon Sep 17 00:00:00 2001 From: Mohammad Mortazavi Date: Sat, 2 Dec 2023 11:26:11 +0330 Subject: [PATCH 12/12] Update query-builder.md Co-Authored-By: Jeremy Mikola --- docs/query-builder.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/query-builder.md b/docs/query-builder.md index 913b55e0e..4438e889c 100644 --- a/docs/query-builder.md +++ b/docs/query-builder.md @@ -480,7 +480,7 @@ DB::collection('users') ->where('name', 'John') // Push an embedded document as a value to the messages array ->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); // Result: // messages: [ @@ -490,7 +490,7 @@ DB::collection('users') // Or $user->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); ``` @@ -512,7 +512,7 @@ DB::collection('users') // Or $user->push('messages', [ - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); // Result: // messages: [ @@ -520,8 +520,8 @@ $user->push('messages', [ // ] $user->push('messages', [ - [ 'from' => 'Jess Doe', 'message' => 'Hi' ], - [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], + [ 'from' => 'Jess Doe', 'message' => 'Hi' ], + [ 'from' => 'Jane Doe', 'message' => 'Hi John' ], ], true); // Result: // messages: [ @@ -550,7 +550,7 @@ $user->pull('items', ['boots', 'jeans']); // items: ['hat'] ``` -Embedded document and arrays values can also be pulled from the `messages` array. +Embedded document and arrays values can also be removed from the `messages` array. ```php // Latest state: @@ -561,7 +561,7 @@ Embedded document and arrays values can also be pulled from the `messages` array DB::collection('users') ->where('name', 'John') - // It will search for the exact array and pulls it + // Pull an embedded document from the array ->pull('messages', [ [ 'from' => 'Jane Doe', 'message' => 'Hi John' ] ]); @@ -570,7 +570,7 @@ DB::collection('users') // { from: "Jess Doe", message: "Hi" } // ] -// Or pull multiple array +// Or pull multiple embedded documents $user->pull('messages', [ [ 'from' => 'Jane Doe', 'message' => 'Hi John' ],