Client and services

[ob-stripe]

r? @ob-stripe @remi-stripe
cc? @stripe/api-libraries

Introduces a "client + services" API.

This means, for example, instead of

\Stripe\Stripe::setApiKey('sk_test_xxx');
$customer = \Stripe\Customer::retrieve(
  'cus_HG97q60gg1Naih'
);
$customer->delete();

where retrieve, create, update and list are static "collection" methods that live on the class, and save and delete are instance methods

users do

$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xxx',
]);
$stripe->customers->delete('cus_HG97q60gg1Naih', []);

where all methods are instance methods of "service" objects that can be accessed via getters from an initialized $stripe client.

This has some advantages. It permits invoking "delete" without a previous "retrieve". It permits multiple StripeClients to coexist, with different settings. It also is generally more consistent and more amenable to codegen.

How does $stripe->customers->delete work, behind the scenes?

1. $stripe->customers triggers StripeClient.__get
2. StripeClient.__get lazily initializes new CoreServiceFactory and calls CoreServiceFactory.__get, which is implemented in AbstractServiceFactory.__get
3. AbstractServiceFactory.__get calls CoreServiceFactory.getServiceClass
4. CoreServiceFactory.getServiceClass references a static $classMap, which has been codegenned mapping from names like 'customers' to ServiceClasses, like CustomerService, and lazily initializes the corresponding 'Service' class..
5. That class has methods like ->delete, which have also been codegenned, and use AbstractService.request, and AbstractService.buildPath.
6. AbstractService.request ends up calling StripeClient.request (which is implemented in BaseStripeClient.request) to actually perform the HTTP request, as the StripeClient has been passed through through every stage of lazy initialization.

For namespaced resources, CoreServiceFactory.getServiceClass actually does not return a Service class directly, it returns another Service factory, and then that service factory has a .__get and .getServiceClass that resolve to services.

[ob-stripe]

LGTM, but I can't approve my own PR :)

[driesvints]

I don't immediately see it mentioned here but since this was released in a minor release I suspect the old way of doing things is still accounted for?

[remi-stripe]

@driesvints That's correct, we're not removing the old way, we're just adding this new approach and will recommend it moving forward.