Feature request: Some or any array items match an expectation

[paulshryock]

Given some $things which are nested arrays:

getThings(): array {
  return [
    ['something' => ['id' => 1]],
    ['something' => ['id' => 2]],
  ];
}

I would like a way to expect that "some" or "any" of the nested things contains an id of 2.

In a test, I can first drill down inside getThings() and pluck out the something.id's before my expectation:

it('should return a list of things, any of which have something.id of %s', function(int $id) {
  $ids = array_map(
    fn($thing) => $thing['something']['id'],
    getThings(),
  );

  expect($ids)->toContain($id);
})->with([1, 2]);

But currently there seems to be no available expectation available to reach in without doing my own array_map logic outside of the expectation first.

We do have expect()->toContain() and we do have expect()->toMatchArray(), but neither quite works for this scenario of deeply nested arrays.

I don't know what the ideal syntax might be, but maybe something like:

// expect(mixed)->any(Callable)

// Example using ->toBe()
it('should return a list of things, any of which have something.id of %s', fn(int $id) =>
  expect(getThings())
    ->any(fn(array $thing) => $thing['something']['id']
      ->toBe($id)))
        ->with([1, 2]);

// Example using ->toMatchArray()
it('should return a list of things, any of which have something.id of %s', fn(int $id) =>
  expect(getThings())
    ->any(fn(array $thing) => $thing['something']
      ->toMatchArray(['id' => $id])))
        ->with([1, 2]);

or

// expect(mixed)->some(Callable)

// Example using ->toBe()
it('should return a list of things, any of which have something.id of %s', fn(int $id) =>
  expect(getThings())
    ->some(fn(array $thing) => $thing['something']['id']
      ->toBe($id)))
        ->with([1, 2]);

// Example using ->toMatchArray()
it('should return a list of things, any of which have something.id of %s', fn(int $id) =>
  expect(getThings())
    ->some(fn(array $thing) => $thing['something']
      ->toMatchArray(['id' => $id])))
        ->with([1, 2]);

This is very similar to expect()->every, except instead of insisting that every item meets a given expectation, it would check that some or any of the items meet a given expectation.