stripe-php: Wrong php-doc types for Subscriptions properties

\Stripe\Subscription have * @property int $trial_end but according to api documentation this can be now.

Same with * @property int $billing_cycle_anchor (it’s also can be now) and * @property Plan $plan (it`s can accept hash string).

Maybe replace with int|string and Plan|string?

About this issue

  • Original URL
  • State: closed
  • Created 8 years ago
  • Comments: 15 (12 by maintainers)

Most upvoted comments

This is a bit tricky. We’re trying to move away from the “update properties then call save()” approach, precisely because it conflates resource attributes and request parameters in a confusing way (for instance, prorate is a valid parameter in subscription update requests, but it’s not an attribute on the subscription object).

The now recommended way to update resources is to use the static method update() with the resource’s ID as the first argument and the array of params as the second argument (cf. https://stripe.com/docs/api/subscriptions/update?lang=php). However, since many existing Stripe users rely on the save() method, we will keep supporting it for a long time.

My gut feel is that the PHPDoc should only describe the properties of the resource, not the possible update parameters, but I understand that this is a bit confusing because in many cases, resource properties and update parameters have the same names and types.

cc @brandur-stripe @nickdnk Do you have an opinion on this?

Also @property-read may be used for properties and @deprecated for save().

My hope is that once we move to an autogenerated world, we would document update parameters in the PHPDoc of the update() method for each resource (we would no longer use common traits and generate the methods directly for each resource), and properly flag save() as deprecated in favor of update(). I’m not sure that PHPDoc supports documenting array keys though.