[8.x] Added sole() and soleWhere() methods for Collections #37034

ash-jc-allen · 2021-04-18T19:01:25Z

Hey! This PR should hopefully add new sole() and soleWhere() methods to Collections and LazyCollections. I've taken inspiration from the similar sole() method for the database queries and think that these could be pretty handy additions.

The sole() method should work in a similar way to the first() method does but does not require a default value as a second parameter. Likewise, the soleWhere() method should work in a similar way to the firstWhere() method.

If either of the methods are executed and there are no items to be returned, an Illuminate\Collections\ItemNotFoundException will be thrown. If the either of the methods are executed are there is more than one item to be returned, an Illuminate\Collections\MultipleItemsFoundException will be thrown.

Here's a couple of quick examples of how they could be used:

sole():

$collection = collect([
    ['name' => 'foo'],
    ['name' => 'bar'],
    ['name' => 'bar'],
]);

// $result will be equal to: ['name' => 'foo']
$result = $collection->where('name', 'foo')->sole();

// $result will be equal to: ['name' => 'foo']
$result = $collection->sole(function ($value) {
    return $value['name'] === 'foo';
});

// This will throw an ItemNotFoundException
$collection->where('name', 'INVALID')->sole();

// This will throw a MultipleItemsFoundException
$collection->where('name', 'bar')->sole();

soleWhere():

$collection = collect([
    ['name' => 'foo'],
    ['name' => 'bar'],
    ['name' => 'bar'],
]);

// $result will be equal to: ['name' => 'foo']
$result = $collection->soleWhere('name', 'foo');

// This will throw an ItemNotFoundException
$collection->soleWhere('name', 'INVALID');

// This will throw a MultipleItemsFoundException
$collection->soleWhere('name', 'bar');

If there's anything that might need changing on these, please let me know 😄

driesvints · 2021-04-19T07:03:48Z

Ping @JosephSilber

JosephSilber · 2021-04-19T13:31:07Z

I was never a fan of the sole method, but I guess that ship has sailed.

JosephSilber · 2021-04-19T13:14:57Z

src/Illuminate/Collections/Collection.php

+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException


We always use fully qualified class names in DocBlocks.

Ahh okay, sorry I wasn't aware of that. I'll get them changed to be fully qualified

JosephSilber · 2021-04-19T13:15:57Z

src/Illuminate/Collections/Enumerable.php

+    public function sole(callable $callback = null);
+
+    /**
+     * Get the first item by the given key value pair, but only if
+     * exactly one item matches the criteria. Otherwise, throw
+     * an exception.
+     *
+     * @param  string  $key
+     * @param  mixed  $operator
+     * @param  mixed  $value
+     * @return mixed
+     */
+    public function soleWhere($key, $operator = null, $value = null);


We can't add methods to an interface mid-cycle.

Remove these from the interface. After it's merged, submit a separate PR to master to add them to the interface.

That makes sense thinking about it. I'll take this out and make a separate PR if this one gets merged

JosephSilber · 2021-04-19T13:22:41Z

src/Illuminate/Collections/LazyCollection.php

+     * @throws ItemNotFoundException
+     * @throws MultipleItemsFoundException
+     */
+    public function sole(callable $callback = null)


This implementation is way more complex than it needs to be.

Something like this (not tested) should suffice:

public function sole(callable $callback = null) { return $this ->when($callback) ->filter($callback) ->take(2) ->collect() ->sole(); }

I do agree that it's more complex. I was looking at some of the existing code for things like the first() method and just assumed that it had been done like that for a specific reason. I've not really used LazyCollections too much so I wasn't 100% sure on the best way to implement it. Thanks for the advice on this one

JosephSilber · 2021-04-19T13:23:41Z

tests/Support/SupportCollectionTest.php

+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testSoleReturnsFirstItemInCollectionIfOnlyOneExists($collection)


Please also add tests in SupportLazyCollectionIsLazyTest.php ensuring this method is lazy.

Yeah sure, I didn't realise those tests were there, so I'll add some to it

JosephSilber · 2021-04-19T13:25:27Z

src/Illuminate/Collections/Traits/EnumeratesValues.php

+    public function soleWhere($key, $operator = null, $value = null)
+    {
+        return $this->sole($this->operatorForWhere(...func_get_args()));
+    }


Since, unlike the first method, sole doesn't take a $default parameter , there's no need for a separate soleWhere method. Constraints can be passed into the sole method directly, like we do in contains.

That makes sense. So do you suggest removed the soleWhere method completely?

JosephSilber · 2021-04-19T13:26:29Z

src/Illuminate/Collections/Collection.php

+     */
+    public function sole(callable $callback = null)
+    {
+        $items = $this->filter($callback);


The code as is will filter out nulls when no $callback has been provided.

Suggested change

$items = $this->filter($callback);

$items = $this->when($callback)->filter($callback);

Ahh I must have missed that, cheers

JosephSilber · 2021-04-19T14:01:29Z

It's a pity the exceptions aren't shared (maybe down the line in 9.x). Then this:

framework/src/Illuminate/Database/Concerns/BuildsQueries.php

Lines 256 to 266 in 277c2fb

    
           $result = $this->take(2)->get($columns); 
        
           if ($result->isEmpty()) { 
        
               throw new RecordsNotFoundException; 
        
           } 
        
           if ($result->count() > 1) { 
        
               throw new MultipleRecordsFoundException; 
        
           } 
        
           return $result->first();

could be changed to simply:

return $this->take(2)->get($columns)->sole();

ash-jc-allen · 2021-04-19T14:14:30Z

Thanks for the feedback on all of this @JosephSilber! I'll make all of the changes for it now 😄

And I do agree that it'd be cool to have the shared functionality like in your suggestion.

ash-jc-allen · 2021-04-19T14:47:08Z

I've made the changes that you suggested @JosephSilber and from what I can see, they all seem to working. One thing thing I'm not too sure about though is the new test I've added. I have a feeling that I might not have done it right; apologies if that's the case.

JosephSilber

Looking better.

Seems like you forgot to add operator support to sole.

JosephSilber · 2021-04-19T16:38:47Z

tests/Support/SupportLazyCollectionIsLazyTest.php

+    public function testSoleIsLazy()
+    {
+        $data = $this->make([['a' => 1], ['a' => 2], ['a' => 3]]);
+
+        $this->assertEnumeratesCollection($data, 3, function ($collection) {
+            $collection->sole(function ($item) {
+                return $item['a'] === 2;
+            });
+        });
+    }


Suggested change

public function testSoleIsLazy()

{

$data = $this->make([['a' => 1], ['a' => 2], ['a' => 3]]);

$this->assertEnumeratesCollection($data, 3, function ($collection) {

$collection->sole(function ($item) {

return $item['a'] === 2;

});

});

}

public function testSoleIsLazy()

{

$this->assertEnumerates(2, function ($collection) {

try {

$collection->sole();

} catch (MultipleItemsFoundException $e) {

//

}

});

$this->assertEnumeratesOnce(function ($collection) {

$collection->sole(function ($item) {

return $item === 1;

});

});

$this->assertEnumerates(4, function ($collection) {

try {

$collection->sole(function ($item) {

return $item % 2 === 0;

});

} catch (MultipleItemsFoundException $e) {

//

}

});

}

Be sure to also import MultipleItemsFoundException.

Thanks for the suggestion again, I've just pushed up the new test changes :)

JosephSilber · 2021-04-19T17:09:50Z

Seems like you forgot to add operator support to sole.

If it's not added now, we won't be able to add it until 9.x, since it would be a breaking change in the function signature.

ash-jc-allen · 2021-04-19T17:11:23Z

@JosephSilber In your opinion, do you think it's something that should be added now? I can try and add it if so

JosephSilber · 2021-04-19T17:17:12Z

Would be nice.

If you can't figure it out, let me know, and I'll try to find a few minutes to do it for you 👍

ash-jc-allen · 2021-04-19T17:18:09Z

Sweet, I'll take a look at it now then. Thanks again for all the help on this one, I really appreciate it and it's giving me a chance to learn a bit more at the same time 😄

browner12 · 2021-04-19T17:47:01Z

god, this is a lot of extra code to avoid saying

if($collection->count() === 1){
    return $collection->first();
}

ash-jc-allen · 2021-04-19T17:47:33Z

@JosephSilber I think I've added the operator support, but please let me know if I've missed anything

JosephSilber · 2021-04-19T17:51:01Z

src/Illuminate/Collections/Collection.php

+    public function sole($key = null, $operator = null, $value = null)
+    {
+        if (func_num_args() <= 1) {
+            $items = $this->when($key)->filter($key);
+
+            if ($items->isEmpty()) {
+                throw new ItemNotFoundException;
+            }
+
+            if ($items->count() > 1) {
+                throw new MultipleItemsFoundException;
+            }
+
+            return $items->first();
+        }
+
+        return $this->sole($this->operatorForWhere(...func_get_args()));
+    }


A ternary would be a little clearer, and allows dedenting the whole method:

Suggested change

public function sole($key = null, $operator = null, $value = null)

{

if (func_num_args() <= 1) {

$items = $this->when($key)->filter($key);

if ($items->isEmpty()) {

throw new ItemNotFoundException;

}

if ($items->count() > 1) {

throw new MultipleItemsFoundException;

}

return $items->first();

}

return $this->sole($this->operatorForWhere(...func_get_args()));

}

public function sole($key = null, $operator = null, $value = null)

{

$filter = func_num_args() > 1

? $this->operatorForWhere(...func_get_args())

: $key;

$items = $this->when($filter)->filter($filter);

if ($items->isEmpty()) {

throw new ItemNotFoundException;

}

if ($items->count() > 1) {

throw new MultipleItemsFoundException;

}

return $items->first();

}

JosephSilber · 2021-04-19T17:52:12Z

src/Illuminate/Collections/LazyCollection.php

+    public function sole($key = null, $operator = null, $value = null)
+    {
+        if (func_num_args() <= 1) {
+            return $this
+                ->when($key)
+                ->filter($key)
+                ->take(2)
+                ->collect()
+                ->sole();
+        }
+
+        return $this->sole($this->operatorForWhere(...func_get_args()));
+    }


Same here:

Suggested change

public function sole($key = null, $operator = null, $value = null)

{

if (func_num_args() <= 1) {

return $this

->when($key)

->filter($key)

->take(2)

->collect()

->sole();

}

return $this->sole($this->operatorForWhere(...func_get_args()));

}

public function sole($key = null, $operator = null, $value = null)

{

$filter = func_num_args() > 1

? $this->operatorForWhere(...func_get_args())

: $key;

return $this

->when($filter)

->filter($filter)

->take(2)

->collect()

->sole();

}

ash-jc-allen · 2021-04-19T18:12:45Z

@JosephSilber Ah yeah, the ternary makes it look much cleaner, thanks! 😄

ash-jc-allen · 2021-04-19T18:17:45Z

It looks like 2 of the test checks failed, but I don't think I can rerun them myself?

JosephSilber

👍

joelharkes · 2021-04-28T08:29:21Z

src/Illuminate/Collections/Collection.php

+        $items = $this->when($filter)->filter($filter);
+
+        if ($items->isEmpty()) {
+            throw new ItemNotFoundException;


would be nice if the query builder etc would throw the exact same exceptions when calling sole()

#37034 (comment)

driesvints · 2021-08-19T12:25:30Z

This PR apparently introduced a new Illuminate\Collections namespace which doesn't exists. It's not autoloaded. Only the Illuminate\Support namespace exists. I'll send a PR to fix this.

ash-jc-allen · 2021-08-19T12:30:08Z

@driesvints Sorry, my bad here! When I made the exceptions, I must have assumed at the time that the namespace was the same as the file path. I should have double-checked this before pushing 😔

driesvints · 2021-08-19T12:33:28Z

@ash-jc-allen don't worry about it. I've sent in a PR to fix this: #38449

ash-jc-allen added 7 commits April 18, 2021 02:16

Added the 'sole' method for Collections.

1aef429

Style updates.

af6270d

Moved tests.

d9c21db

Updated sole() to work with callbacks.

034bad1

Added tests for the sole() Collection method.

5465ded

Added soleWhere() method and added tests.

04a1df1

Style updates.

d6a023e

JosephSilber reviewed Apr 19, 2021

View reviewed changes

ash-jc-allen added 5 commits April 19, 2021 15:22

Removed sole() and soleWhere() from the Enumerable contract.

534bb57

Removed soleWhere() and simplified sole() method for LazyCollections.

d8cd628

Added when() to sole().

483e43b

Added test for sole().

4e76b91

Style updates.

c0a82d8

JosephSilber reviewed Apr 19, 2021

View reviewed changes

Updated test.

3c4f386

Added operator suport for the sole() method.

2d3b63c

JosephSilber reviewed Apr 19, 2021

View reviewed changes

Replace 'if' statement with ternary.

9c42ab1

JosephSilber approved these changes Apr 19, 2021

View reviewed changes

taylorotwell merged commit 9c42ab1 into laravel:8.x Apr 20, 2021

ash-jc-allen deleted the feature/collection-sole branch April 20, 2021 19:34

ash-jc-allen mentioned this pull request Apr 20, 2021

[9.x] Add sole() to Enumerable contract #37066

Merged

joelharkes reviewed Apr 28, 2021

View reviewed changes

driesvints mentioned this pull request Aug 19, 2021

Illuminate Support Arr class not found. #34292

Closed

driesvints mentioned this pull request Aug 19, 2021

[8.x] Convert non-existant namespace #38449

Merged

		* @throws ItemNotFoundException
		* @throws MultipleItemsFoundException

	$items = $this->filter($callback);
	$items = $this->when($callback)->filter($callback);

[8.x] Added sole() and soleWhere() methods for Collections #37034

[8.x] Added sole() and soleWhere() methods for Collections #37034

Conversation

ash-jc-allen commented Apr 18, 2021 • edited Loading

driesvints commented Apr 19, 2021

JosephSilber commented Apr 19, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JosephSilber Apr 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JosephSilber Apr 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JosephSilber commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

JosephSilber left a comment • edited Loading

Choose a reason for hiding this comment

JosephSilber Apr 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JosephSilber commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

JosephSilber commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

browner12 commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ash-jc-allen commented Apr 19, 2021

ash-jc-allen commented Apr 19, 2021

JosephSilber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

driesvints commented Aug 19, 2021

ash-jc-allen commented Aug 19, 2021

driesvints commented Aug 19, 2021 • edited Loading

ash-jc-allen commented Apr 18, 2021 •

edited

Loading

JosephSilber Apr 19, 2021 •

edited

Loading

JosephSilber Apr 19, 2021 •

edited

Loading

JosephSilber left a comment •

edited

Loading

JosephSilber Apr 19, 2021 •

edited

Loading

driesvints commented Aug 19, 2021 •

edited

Loading