Added more constants, fixed more docs, added missing objects

[nickdnk]

Hello

1. Added Discount, DisputeEvidence and OrderItem objects - none of these extend ApiResource since they don't have an id property which I assume is necessary for that. Anywhere these objects are referenced in phpdocs I've update those from the previously used mixed type. DisputeEvidence isn't really a class since it doesn't have an OBJECT_NAME. If you think it's silly I'll remove it from the PR. I only added it because it exists as a standalone documented object: https://stripe.com/docs/api#dispute_evidence_object. And: Are Discount and OrderItem supposed to be in the Util map?

2. Added charge decline code constants to Charge - following the logic elsewhere in the library. I was not sure if this should be on Card or on Charge, but I think Charge, no? Or perhaps we should move them to the \Stripe\Error\Card object?

3. Added payout failure code constants to Payout - following the logic elsewhere in the library.

4. Indented Subscription status constants like elsewhere - minor edit.

Some things I noticed:

The Topup object is missing from the documentation, even though it links to it itself: https://stripe.com/docs/api#topup_object - it doesn't exist on the page. For this reason I can't check if the phpdocs match.

The SourceTransaction object - what is that? Why do we have it? I can't find it anywhere in the documentation. Isn't this just a normal Charge object used as a source for transactions? See https://stripe.com/docs/connect/charges-transfers#transfer-availability

And; is there somehow we can follow changes made to the API? It doesn't seem to be documented anywhere when changes to properties take place, which makes it quite tedious to go through all of the objects again and again to keep them updated. I assume this is the reason the phpdocs were outdated in the first place.

Cheers

[ob-stripe]

Hey Nick. Awesome work as usual.

Added Discount, DisputeEvidence and OrderItem objects - none of these extend ApiResource since they don't have an id property which I assume is necessary for that. Anywhere these objects are referenced in phpdocs I've update those from the previously used mixed type. DisputeEvidence isn't really a class since it doesn't have an OBJECT_NAME. If you think it's silly I'll remove it from the PR. I only added it because it exists as a standalone documented object: https://stripe.com/docs/api#dispute_evidence_object. And: Are Discount and OrderItem supposed to be in the Util map?

So, yes, you do need to add those new objects to the Util map so the deserializer knows about them. If you don't add them, then the objects will be deserialized to default StripeObjects instances.

This also means that you should remove the DisputeEvidence class: because it doesn't have an object property, the deserializer won't know about it. (We could write custom deserialization login to always cast instances to the correct class, like we do in stripe-java, but I would really rather avoid introducing this kind of complexity in the PHP library.)

Also, you're correct that your new classes should not extend ApiResource, but they should extend StripeObject for backwards compatibility (so users can still access attributes via both attribute (->foo) and array (['foo']) syntax, etc.).

Overall though, I have some concerns about adding those new classes purely for the sake of describing the attributes with phpdoc. @brandur-stripe wdyt?

Added charge decline code constants to Charge - following the logic elsewhere in the library. I was not sure if this should be on Card or on Charge, but I think Charge, no? Or perhaps we should move them to the \Stripe\Error\Card object?

No, I think Charge is the right place for these. Sadly, non-card payments can be declined too :)

The Topup object is missing from the documentation, even though it links to it itself: https://stripe.com/docs/api#topup_object - it doesn't exist on the page. For this reason I can't check if the phpdocs match.

Topups are a private beta feature. The link is valid, but you need to be logged into an account that has been invited into the beta to be able to view it.

The SourceTransaction object - what is that? Why do we have it? I can't find it anywhere in the documentation. Isn't this just a normal Charge object used as a source for transactions? See https://stripe.com/docs/connect/charges-transfers#transfer-availability

No, SourceTransaction describes a transaction on a receiver-type source like ACH Credit Transfer: https://stripe.com/docs/sources/ach-credit-transfer#source-transactions. The object is not yet described in the API reference, but you can view an example in the link above. It might be difficult to fully describe it with phpdoc because, like Source objects, it is polymorphic depending on the source's type.

And; is there somehow we can follow changes made to the API? It doesn't seem to be documented anywhere when changes to properties take place, which makes it quite tedious to go through all of the objects again and again to keep them updated. I assume this is the reason the phpdocs were outdated in the first place.

At this time, your best bet is to look at the diffs in the OpenAPI spec: https://github.com/stripe/openapi. Ultimately we'll be able to autogenerate the phpdocs directly from the spec, but we're not quite there yet.

[nickdnk]

@ob-stripe

Hey

I removed the DisputeEvidence class and made the other changes you mentioned. I'll leave it up to you guys to decide if you want OrderItem and Discount as classes in the library, since they don't "do" anything. I think it's fair to have them because of the OBJECT_NAME constant - for consistency and to support phpdocs. They now extend StripeObject.

I added those classes to Util and init.php.

I'll rebase to one commit once we've agreed on everything.

[nickdnk]

Does this mean that all variables currently defined as mixed could/should be StripeObject ?

[nickdnk]

I've just added the invoice_pdf and hosted_invoice_url properties to Invoice - these are new :)

[nickdnk]

Added the active property to Plan

[brandur-stripe]

Thanks for keeping this one alive and updated @nickdnk!

If you get a chance, could you squash your commits? Otherwise we'll do it for you when we bring it in (and the commit message might not be as good).

Overall though, I have some concerns about adding those new classes purely for the sake of describing the attributes with phpdoc. @brandur-stripe wdyt?

Sorry @ob-stripe, I totally missed this @ to me last time. I guess I could see it either way, but IMO since these are considered first class API objects (i.e. they have their own sections in the API reference), it's okay to have them as separate classes, so I'd +1 this as currently implemented. I'll defer to you though.

I did a quick pass on the changes otherwise too, and LGTM.

ptal @ob-stripe

[nickdnk]

@brandur-stripe Squashed as requested :)
Edit: I just noticed I forgot to change the discount property of Subscription from mixed to Discount. I just did that and rebased again.

[ob-stripe]

LGTM!

[ob-stripe]

Released as 6.8.0. Thanks again @nickdnk :)