[7.x] Conditionally returning appended attributes in API resources

[jessarcher]

I recently needed to return an attribute in an API Resource only when it had been explicitly appended to the model.

I couldn't find a nice public method to determine whether something had been appended to a model, so this PR adds a very simple public hasAppended() method to the HasAttributes trait so it can be easily checked on any model instance.

Then to improve the ergonomics inside the API Resource, I added a whenAppended() method to the ConditionallyLoadsAttributes trait that I think has nice symmetry with the other conditional "when" methods like when() and whenLoaded().

The usage is then something like this:

public function toArray($request)
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'is_subscribed' => $this->whenAppended('is_subscribed'),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

return new UserResource($user->append('is_subscribed'));

This is particularly useful when an accessor contains information that should only sometimes be returned, or where an accessor might make additional database requests that you only want to occur deliberately.

Similar to the whenLoaded() method, you can optionally include the value to return if different than the accessor, as well as a default value.

If this is a welcome addition, please let me know and I will add tests. I can also PR the "Conditional Attributes" section of the API Resources docs if warranted.

[taylorotwell]

Seems simple enough. 👍

[taylorotwell]

Feel free to continue with anything else you wanted to add here.

[jessarcher]

Thanks @taylorotwell. I've added a few tests so I think it's good to go :)

[francoism90]

Thanks! I can finally remove my trait. :)