feat: add plus operation

[drupol]

This should fix #313

This PR:

• Fix ...
• Provide ...
• It breaks backward compatibility
• Is covered by unit tests
• Has static analysis tests (psalm, phpstan)
• Has documentation
• Is an experimental thing

Follows #. Related to #. Fixes #.

[what-the-diff]

PR Summary

• Introduction of a new file Plus.php
  Added a new file named Plus.php which contains a class known as Plus. This class is part of the Operation namespace and will likely contribute to the mathematical functions of the application.

[rela589n]

@drupol , does it make any sense to remove duplicated indexes in the existing collection? I assume it would be more apparent if these were kept. Consider following test (fails with current implementation):

public function testPlusDoesNotRemoveExistingDuplicatedIndices(): void
{
    $collection = Collection::fromIterable([
        ['id' => 1],
        ['id' => 2],
    ]);

    $result = $collection
        ->unwrap()
        ->plus(['id' => 3, 'id2' => 4])
        ->wrap()
        ->all(false)
    ;

    self::assertSame([
        ['id' => 1],
        ['id' => 2],
        ['id2' => 4],
    ], $result);
}

Moreover, it would be really pity if plus([]) would drop all key duplicates. The following test fails as well:

public function testPlusEmptyArrayDoesNotModifyCollection(): void
{
    $collection = Collection::fromIterable([
        ['id' => 1],
        ['id' => 2],
    ]);

    $result = $collection
        ->unwrap()
        ->plus([])
        ->wrap()
        ->all(false)
    ;

    self::assertSame([
        ['id' => 1],
        ['id' => 2],
    ], $result);
}

[drupol]

Very nice catch and test case. I will see how we can improve the implementation. Feel free to come up with ideas.

[drupol]

I updated the tests and the implementation, this is a bit uglier, but AFAIK there's no other alternative.

[drupol]

@rela589n Are you willing to contribute to the documentation for this operation?

[github-actions]

Since this pull request has not had any activity within the last 5 days, I have marked it as stale.
I will close it if no further activity occurs within the next 5 days.

[drupol]

No more feedback from the reporter, closing this PR.