[5.5] Add buildToDictionary Method

[ConnorVG]

I've came across the need to build a dictionary a few times and each time it's something ugly or overly busy (doing too much for what it is). I found the perfect use case, HasOneOrMany's buildDictionary method.

This extracts a bit of logic from the mapToGroups method; no extra code is added, it's just extracted.

See this Twitter chain for a bit of context: https://twitter.com/ConnorVG/status/913062913837060098

Please note, I haven't added tests for mapToDictionary as-of yet (though they're currently covered by mapToGroups, it will still need its own tests obviously).

[taylorotwell]

Can you provide an example or description of what this does exactly?

[taylorotwell]

For example, can we add tests for mapToDictionary?

[ConnorVG]

Will do, need to take care of some work then I'll jump on it quickly.

[ConnorVG]

Quickly added some tests based on the mapToGroups tests.

The best example I can think of, in terms of its functionality, is the dictionary mapping in HasOneOrMany:

https://github.com/ConnorVG/framework/blob/7d8d81693aaa18d07e3fe0cd6e380a7518361406/src/Illuminate/Database/Eloquent/Relations/HasOneOrMany.php#L163-L170

vs

https://github.com/laravel/framework/blob/5.5/src/Illuminate/Database/Eloquent/Relations/HasOneOrMany.php#L163-L176

I've used it locally for something similar, matching a bunch of Api results to a bunch of models based on a specific key (creator_id and proposal_id, in my case). This is done simply like this:

[taylorotwell]

How is this different than mapWithKeys()?

[ConnorVG]

The main differences are the same as the main differences between mapWithKeys and mapToGroups:

1. It doesn't mutate based on the k/v, just the value;
2. The callback returns the respective k/v pair to be set in the results, it doesn't return an array of k/v pairs.