Add generic parameter to \Stripe\Collection usages (#1241)

* Add generic parameter to \Stripe\Collection usages

lib/Account.php

@@ -26,7 +26,7 @@
  * @property string $default_currency Three-letter ISO currency code representing the default currency for the account. This must be a currency that <a href="https://stripe.com/docs/payouts">Stripe supports in the account's country</a>.
  * @property bool $details_submitted Whether account details have been submitted. Standard accounts cannot receive payouts before this is true.
  * @property null|string $email An email address associated with the account. You can treat this as metadata: it is not used for authentication or messaging account holders.
- * @property \Stripe\Collection $external_accounts External accounts (bank accounts and debit cards) currently attached to this account
+ * @property \Stripe\Collection<\Stripe\BankAccount|\Stripe\Card> $external_accounts External accounts (bank accounts and debit cards) currently attached to this account
  * @property \Stripe\StripeObject $future_requirements
  * @property \Stripe\Person $individual <p>This is an object representing a person associated with a Stripe account.</p><p>A platform cannot access a Standard or Express account's persons after the account starts onboarding, such as after generating an account link for the account. See the <a href="https://stripe.com/docs/connect/standard-accounts">Standard onboarding</a> or <a href="https://stripe.com/docs/connect/express-accounts">Express onboarding documentation</a> for information about platform pre-filling and account onboarding steps.</p><p>Related guide: <a href="https://stripe.com/docs/connect/identity-verification-api#person-information">Handling Identity Verification with the API</a>.</p>
  * @property \Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
@@ -184,7 +184,7 @@ public function deauthorize($clientId = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of persons
+     * @return \Stripe\Collection<\Stripe\Person> the list of persons
      */
     public function persons($params = null, $opts = null)
     {
@@ -228,7 +228,7 @@ public function reject($params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of capabilities
+     * @return \Stripe\Collection<\Stripe\Capability> the list of capabilities
      */
     public static function allCapabilities($id, $params = null, $opts = null)
     {
@@ -273,7 +273,7 @@ public static function updateCapability($id, $capabilityId, $params = null, $opt
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of external accounts (BankAccount or Card)
+     * @return \Stripe\Collection<\Stripe\BankAccount|\Stripe\Card> the list of external accounts (BankAccount or Card)
      */
     public static function allExternalAccounts($id, $params = null, $opts = null)
     {
@@ -362,7 +362,7 @@ public static function createLoginLink($id, $params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of persons
+     * @return \Stripe\Collection<\Stripe\Person> the list of persons
      */
     public static function allPersons($id, $params = null, $opts = null)
     {

lib/ApplicationFee.php

@@ -18,7 +18,7 @@
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property null|string|\Stripe\Charge $originating_transaction ID of the corresponding charge on the platform account, if this fee was the result of a charge using the <code>destination</code> parameter.
  * @property bool $refunded Whether the fee has been fully refunded. If the fee is only partially refunded, this attribute will still be false.
- * @property \Stripe\Collection $refunds A list of refunds that have been applied to the fee.
+ * @property \Stripe\Collection<\Stripe\StripeObject> $refunds A list of refunds that have been applied to the fee.
  */
 class ApplicationFee extends ApiResource
 {
@@ -37,7 +37,7 @@ class ApplicationFee extends ApiResource
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of fee refunds
+     * @return \Stripe\Collection<\Stripe\ApplicationFeeRefund> the list of fee refunds
      */
     public static function allRefunds($id, $params = null, $opts = null)
     {

lib/BitcoinReceiver.php

@@ -27,7 +27,7 @@
  * @property null|\Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  * @property null|string $payment The ID of the payment created from the receiver, if any. Hidden when viewing the receiver with a publishable key.
  * @property null|string $refund_address The refund address of this bitcoin receiver.
- * @property \Stripe\Collection $transactions A list with one entry for each time that the customer sent bitcoin to the receiver. Hidden when viewing the receiver with a publishable key.
+ * @property \Stripe\Collection<\Stripe\BitcoinTransaction> $transactions A list with one entry for each time that the customer sent bitcoin to the receiver. Hidden when viewing the receiver with a publishable key.
  * @property bool $uncaptured_funds This receiver contains uncaptured funds that can be used for a payment or refunded.
  * @property null|bool $used_for_payment Indicate if this source is used for payment.
  */

lib/Charge.php

@@ -49,7 +49,7 @@
  * @property null|string $receipt_number This is the transaction number that appears on email receipts sent for this charge. This attribute will be <code>null</code> until a receipt has been sent.
  * @property null|string $receipt_url This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
  * @property bool $refunded Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
- * @property \Stripe\Collection $refunds A list of refunds that have been applied to the charge.
+ * @property \Stripe\Collection<\Stripe\Refund> $refunds A list of refunds that have been applied to the charge.
  * @property null|string|\Stripe\Review $review ID of the review associated with this charge if one exists.
  * @property null|\Stripe\StripeObject $shipping Shipping information for the charge.
  * @property null|\Stripe\Account|\Stripe\AlipayAccount|\Stripe\BankAccount|\Stripe\BitcoinReceiver|\Stripe\Card|\Stripe\Source $source This is a legacy field that will be removed in the future. It contains the Source, Card, or BankAccount object used for the charge. For details about the payment method used for this charge, refer to <code>payment_method</code> or <code>payment_method_details</code> instead.

lib/Checkout/Session.php

@@ -41,7 +41,7 @@
  * @property null|\Stripe\StripeObject $customer_details The customer details including the customer's tax exempt status and the customer's tax IDs. Only present on Sessions in <code>payment</code> or <code>subscription</code> mode.
  * @property null|string $customer_email If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the <code>customer</code> attribute.
  * @property int $expires_at The timestamp at which the Checkout Session will expire.
- * @property \Stripe\Collection $line_items The line items purchased by the customer.
+ * @property \Stripe\Collection<\Stripe\LineItem> $line_items The line items purchased by the customer.
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property null|string $locale The IETF language tag of the locale Checkout is displayed in. If blank or <code>auto</code>, the browser's locale is used.
  * @property null|\Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
@@ -124,7 +124,7 @@ public function expire($params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of items
+     * @return \Stripe\Collection<\Stripe\LineItem> the list of items
      */
     public static function allLineItems($id, $params = null, $opts = null)
     {

lib/Collection.php

@@ -5,10 +5,13 @@
 /**
  * Class Collection.
  *
+ * @template TStripeObject of StripeObject
+ * @template-implements \IteratorAggregate<TStripeObject>
+ *
  * @property string $object
  * @property string $url
  * @property bool $has_more
- * @property \Stripe\StripeObject[] $data
+ * @property TStripeObject[] $data
  */
 class Collection extends StripeObject implements \Countable, \IteratorAggregate
 {
@@ -61,6 +64,14 @@ public function offsetGet($k)
         throw new Exception\InvalidArgumentException($msg);
     }
 
+    /**
+     * @param null|array $params
+     * @param null|array|string $opts
+     *
+     * @throws Exception\ApiErrorException
+     *
+     * @return Collection<TStripeObject>
+     */
     public function all($params = null, $opts = null)
     {
         self::_validateParams($params);
@@ -78,6 +89,14 @@ public function all($params = null, $opts = null)
         return $obj;
     }
 
+    /**
+     * @param null|array $params
+     * @param null|array|string $opts
+     *
+     * @throws Exception\ApiErrorException
+     *
+     * @return TStripeObject
+     */
     public function create($params = null, $opts = null)
     {
         self::_validateParams($params);
@@ -88,6 +107,15 @@ public function create($params = null, $opts = null)
         return Util\Util::convertToStripeObject($response, $opts);
     }
 
+    /**
+     * @param string $id
+     * @param null|array $params
+     * @param null|array|string $opts
+     *
+     * @throws Exception\ApiErrorException
+     *
+     * @return TStripeObject
+     */
     public function retrieve($id, $params = null, $opts = null)
     {
         self::_validateParams($params);
@@ -134,7 +162,7 @@ public function getReverseIterator()
     }
 
     /**
-     * @return \Generator|StripeObject[] A generator that can be used to
+     * @return \Generator|TStripeObject[] A generator that can be used to
      *    iterate across all objects across all pages. As page boundaries are
      *    encountered, the next page will be fetched automatically for
      *    continued iteration.
@@ -197,7 +225,7 @@ public function isEmpty()
      * @param null|array $params
      * @param null|array|string $opts
      *
-     * @return Collection
+     * @return Collection<TStripeObject>
      */
     public function nextPage($params = null, $opts = null)
     {
@@ -225,7 +253,7 @@ public function nextPage($params = null, $opts = null)
      * @param null|array $params
      * @param null|array|string $opts
      *
-     * @return Collection
+     * @return Collection<TStripeObject>
      */
     public function previousPage($params = null, $opts = null)
     {
@@ -247,7 +275,7 @@ public function previousPage($params = null, $opts = null)
     /**
      * Gets the first item from the current page. Returns `null` if the current page is empty.
      *
-     * @return null|\Stripe\StripeObject
+     * @return null|TStripeObject
      */
     public function first()
     {
@@ -257,7 +285,7 @@ public function first()
     /**
      * Gets the last item from the current page. Returns `null` if the current page is empty.
      *
-     * @return null|\Stripe\StripeObject
+     * @return null|TStripeObject
      */
     public function last()
     {

lib/CreditNote.php

@@ -21,7 +21,7 @@
  * @property int $discount_amount The integer amount in %s representing the total amount of discount that was credited.
  * @property \Stripe\StripeObject[] $discount_amounts The aggregate amounts calculated per discount for all line items.
  * @property string|\Stripe\Invoice $invoice ID of the invoice.
- * @property \Stripe\Collection $lines Line items that make up the credit note
+ * @property \Stripe\Collection<\Stripe\CreditNoteLineItem> $lines Line items that make up the credit note
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property null|string $memo Customer-facing text that appears on the credit note PDF.
  * @property null|\Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
@@ -102,7 +102,7 @@ public function voidCreditNote($params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of credit note line items
+     * @return \Stripe\Collection<\Stripe\CreditNoteLineItem> the list of credit note line items
      */
     public static function allLines($id, $params = null, $opts = null)
     {

lib/Customer.php

@@ -32,11 +32,11 @@
  * @property null|string $phone The customer's phone number.
  * @property null|string[] $preferred_locales The customer's preferred locales (languages), ordered by preference.
  * @property null|\Stripe\StripeObject $shipping Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
- * @property \Stripe\Collection $sources The customer's payment sources, if any.
- * @property \Stripe\Collection $subscriptions The customer's current subscriptions, if any.
+ * @property \Stripe\Collection<\Stripe\Account|\Stripe\AlipayAccount|\Stripe\BankAccount|\Stripe\BitcoinReceiver|\Stripe\Card|\Stripe\Source> $sources The customer's payment sources, if any.
+ * @property \Stripe\Collection<\Stripe\Subscription> $subscriptions The customer's current subscriptions, if any.
  * @property \Stripe\StripeObject $tax
  * @property null|string $tax_exempt Describes the customer's tax exemption status. One of <code>none</code>, <code>exempt</code>, or <code>reverse</code>. When set to <code>reverse</code>, invoice and receipt PDFs include the text <strong>&quot;Reverse charge&quot;</strong>.
- * @property \Stripe\Collection $tax_ids The customer's tax IDs.
+ * @property \Stripe\Collection<\Stripe\TaxId> $tax_ids The customer's tax IDs.
  */
 class Customer extends ApiResource
 {
@@ -87,7 +87,7 @@ public function deleteDiscount($params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection list of PaymentMethods
+     * @return \Stripe\Collection<\Stripe\Customer> list of PaymentMethods
      */
     public static function allPaymentMethods($id, $params = null, $opts = null)
     {
@@ -108,7 +108,7 @@ public static function allPaymentMethods($id, $params = null, $opts = null)
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of customer balance transactions
+     * @return \Stripe\Collection<\Stripe\CustomerBalanceTransaction> the list of customer balance transactions
      */
     public static function allBalanceTransactions($id, $params = null, $opts = null)
     {
@@ -167,7 +167,7 @@ public static function updateBalanceTransaction($id, $balanceTransactionId, $par
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of payment sources (AlipayAccount, BankAccount, BitcoinReceiver, Card or Source)
+     * @return \Stripe\Collection<\Stripe\AlipayAccount|\Stripe\BankAccount|\Stripe\BitcoinReceiver|\Stripe\Card|\Stripe\Source> the list of payment sources (AlipayAccount, BankAccount, BitcoinReceiver, Card or Source)
      */
     public static function allSources($id, $params = null, $opts = null)
     {
@@ -241,7 +241,7 @@ public static function updateSource($id, $sourceId, $params = null, $opts = null
      *
      * @throws \Stripe\Exception\ApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of tax ids
+     * @return \Stripe\Collection<\Stripe\TaxId> the list of tax ids
      */
     public static function allTaxIds($id, $params = null, $opts = null)
     {

lib/File.php

@@ -20,7 +20,7 @@
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property null|int $expires_at The time at which the file expires and is no longer available in epoch seconds.
  * @property null|string $filename A filename for the file, suitable for saving to a filesystem.
- * @property null|\Stripe\Collection $links A list of <a href="https://stripe.com/docs/api#file_links">file links</a> that point at this file.
+ * @property null|\Stripe\Collection<\Stripe\FileLink> $links A list of <a href="https://stripe.com/docs/api#file_links">file links</a> that point at this file.
  * @property string $purpose The <a href="https://stripe.com/docs/file-upload#uploading-a-file">purpose</a> of the uploaded file.
  * @property int $size The size in bytes of the file object.
  * @property null|string $title A user friendly title for the document.

lib/Invoice.php

@@ -80,7 +80,7 @@
  * @property null|string $hosted_invoice_url The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
  * @property null|string $invoice_pdf The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
  * @property null|\Stripe\ErrorObject $last_finalization_error The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
- * @property \Stripe\Collection $lines The individual line items that make up the invoice. <code>lines</code> is sorted as follows: invoice items in reverse chronological order, followed by the subscription, if any.
+ * @property \Stripe\Collection<\Stripe\InvoiceLineItem> $lines The individual line items that make up the invoice. <code>lines</code> is sorted as follows: invoice items in reverse chronological order, followed by the subscription, if any.
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property null|\Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  * @property null|int $next_payment_attempt The time at which payment will next be attempted. This value will be <code>null</code> for invoices where <code>collection_method=send_invoice</code>.
@@ -153,7 +153,7 @@ class Invoice extends ApiResource
      *
      * @throws StripeExceptionApiErrorException if the request fails
      *
-     * @return \Stripe\Collection the list of lines (InvoiceLineItem)
+     * @return \Stripe\Collection<\Stripe\InvoiceLineItem> the list of lines (InvoiceLineItem)
      */
     public static function allLines($id, $params = null, $opts = null)
     {