[5.5] Add ability to pass callback to whenLoaded Resource method

[aaronhuisinga]

Currently, the whenLoaded method for API Resources is only able to return the relationship object.
A similar method, whenPivotLoaded, allows a callback to be passed, which will be added to the returned array.
This PR adds this similar functionality to the whenLoaded method. If a callback is passed, the return value of that callback will be added to the array to be returned. If no callback is passed, the relationship object is returned, as is the current behavior. This should be a fully backward compatible addition.

Behavior when no callback is specified:

/**
 * Transform the resource into an array.
 *
 * @param  \Illuminate\Http\Request
 * @return array
 */
public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'author' => new AuthorResource($this->whenLoaded('author')),
    ];
}

// Would return
[
    'id' => 1,
    'title' => 'Post Title',
    'author' => ['id' => 1, 'name' => 'Taylor Otwell'],
]

Behavior when a callback is specified:

/**
 * Transform the resource into an array.
 *
 * @param  \Illuminate\Http\Request
 * @return array
 */
public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'author_name' => $this->whenLoaded('author'), function() {
            return $this->author->name;
        }),
    ];
}

// Would return
[
    'id' => 1,
    'title' => 'Post Title',
    'author_name' => 'Taylor Otwell',
]

This isn't the most practical example ever, but being able to pass a callback is very handy for things such as counts or other adjustments to the related object that don't necessarily need to be part of a dedicated Resource object for a model.

[deleugpn]

Can the same result be achieved with with attributes?

[aaronhuisinga]

@deleugpn I do not believe so. I believe the only method that checks whether or not a relationship has been loaded is the isLoaded method. Everything else I've been able to find either causes an Exception if the relationship is not loaded, or else causes an n+1 problem.