Use traits for API operations methods

[ob-stripe]

r? @brandur-stripe
cc @stripe/api-libraries

Traits are a feature available in PHP 5.4+. Now that we're dropping support for PHP <5.4, we can start using traits to factorize code.

This PR adds traits for common API operations methods (CRUD + list).

[brandur-stripe]

Minor, but maybbeeee consider alphabetizing this lists just so that we have stable sorting if new traits are added down the line.

[ob-stripe]

Yeah, good point. Done :)

[brandur-stripe]

+1 million. This is awesome!

Maybe the one large-ish thing I noticed: when you pull in one of the new traits, it assumes the existence presence of a method on its new host like _retrieve_, meaning that the only class you could ever plausibly mix one of these into is ApiResource. Maybe this isn't that bad, but it seems a little unusual for these traits to have an undocumented, implicit dependency on ApiResource.

(And to be fair, I think the same thing is happening in languages like Ruby already.)

I don't think this will be that much of a problem in practice, and I'm having trouble coming up with specific recommendations. We could try moving _retrieve, _create, etc. to a more general utility class that each trait can just invoke statically, but even then, you'd still need to figure out what to do with classUrl, _staticRequest, etc., which would be hard.

You could check for the presence of methods you're about to use like _retrieve before you use them so that at least you could produce a nicer error message, but that may not be worth the runtime overhead (I tried to see if there's a "included" callback for traits like there is in Ruby, but I guess not).

Anyway, probably not a big deal, but wanted to bring it up for a little discussion.

[ob-stripe]

Yeah, this is something that crossed my mind as well. Unfortunately PHP does not have a syntax to ensure that a trait is only applied to instances of a certain class, so the only way to enforce this would be to check at runtime.

I will add some PHPDoc to each trait to explicitly flag that these traits can and should only be applied to classes that derive from ApiResource.

[brandur-stripe]

I will add some PHPDoc to each trait to explicitly flag that these traits can and should only be applied to classes that derive from ApiResource.

Cool. Sounds reasonable. Thanks for taking a look!