Add idempotency_key constant

[Firehed]

I've found it rather easy to mistype and misremember the idempotecy key option while performing Stripe integrations. By adding the value as a constant, that class of error can be avoided during development by aid of IDEs, static analysis tools, etc. This gives a bit of a faster feedback cycle during development as well.

e.g. this:

use Stripe\StripeClient;
// ...
$customer = $stripe->customers->create([
  'description' => '...',
], [
  'idempotency_key' => 'KG5LxwFBepaKHyUD'
]);

Could (but is not forced) to become this:

use Stripe\StripeClient;
// ...
$customer = $stripe->customers->create([
  'description' => '...',
], [
  StripeClient::IDEMPOTENCY_KEY => 'KG5LxwFBepaKHyUD'
]);

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[richardm-stripe]

Hi @Firehed. Thank you for the contribution!

I agree with the goal of letting IDEs and static analysis tools help out here, and @helenye-stripe and I looked into this a little bit.

Constants are a little unsatisfying, as the user still has to discover that the constant exists and remember to use it. Providing a constant would help a user who is fortunate enough to do that -- but the better thing would be if we could tell IDEs/static analysis tools directly in the PHPDoc type what keys are allowed. Something like #1646.

Support for "array shapes" support is still a bit nascent in PHP tooling -- it doesn't look like IDEs give you autocomplete, and it looks like only Psalm and not PHPStan typechecks them the way I would want in order to prevent a typo -- but I think this is the direction the tooling is going and would rather build towards that future vs. adding constants. Does that make sense?

---

I'm closing your PR as constants aren't currently our chosen approach and so it's unlikely we will merge this, but feel free to continue discussing here!

[Firehed]

@richardm-stripe Understood, and thanks for your detailed response. I agree that constants are non-ideal, and expect that better-integrated options aren't suitable to provide the (quite deep) PHP version backwards compatibility your SDK currently offers.

Done right, I think allowing users to leverage the 8.0+ named arguments is probably the ideal approach:

$stripe->paymentIntents->create($existingData, idempotencyKey: 'some-value')

Technically the SDK itself could still be backwards-compatible in terms of PHP syntax (this option would only be available to users on current versions), but replacing $opts with a bunch of optional values that represent the currently-supported values would be quite an undertaking - even without considering backwards-compatibility challenges.

e.g.

public function create($params = null, $opts = null)

would instead become something like

public function create(
  $params = null,
  $idempotencyKey = null,
  $stripeAccount = null,
  $stripeVersion = null,
  // ...
)

While I think it's technically possible to do (maybe even without a BC break, though with a lot of spooky logic), I suspect it's not worth the undertaking for the Stripe team. Perhaps the codegen going into the SDK builds could handle it? You'd know better than me!

If it is a route you've got any interest in pursuing, I'd be happy to brainstorm on ergonomics (as well as pitfalls I've encountered making similar changes) - just say the word.