Merge pull request #931 from stripe/richardm/codegen-72527e3

Add support for the `LineItem` resource and APIs

.travis.yml

@@ -37,7 +37,7 @@ matrix:
 
 env:
   global:
-    - STRIPE_MOCK_VERSION=0.89.0
+    - STRIPE_MOCK_VERSION=0.90.0
 cache:
   directories:
     - $HOME/.composer/cache/files

init.php

@@ -102,6 +102,7 @@
 require __DIR__ . '/lib/Issuing/Cardholder.php';
 require __DIR__ . '/lib/Issuing/Dispute.php';
 require __DIR__ . '/lib/Issuing/Transaction.php';
+require __DIR__ . '/lib/LineItem.php';
 require __DIR__ . '/lib/LoginLink.php';
 require __DIR__ . '/lib/Mandate.php';
 require __DIR__ . '/lib/Order.php';

lib/BillingPortal/Session.php

@@ -5,13 +5,13 @@
 /**
  * A Session describes the instantiation of the self-serve portal for a particular
  * customer. By visiting the self-serve portal's URL, the customer can manage their
- * subscriptions and view their invoice payment history. For security reasons,
- * Sessions are short-lived and will expire if the customer does not visit the URL.
- * Create Sessions on-demand.
+ * subscriptions and billing details. For security reasons, Sessions are
+ * short-lived and will expire if the customer does not visit the URL. Create
+ * Sessions on-demand.
  *
- * Related guide: <a
- * href="https://stripe.com/docs/billing/subscriptions/integrating-self-serve">self-serve
- * Portal</a>.
+ * Integration guide: <a
+ * href="https://stripe.com/docs/billing/subscriptions/integrating-self-serve-portal">Billing
+ * self-serve portal</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/Checkout/Session.php

@@ -28,6 +28,7 @@
  * @property null|string|\Stripe\Customer $customer The ID of the customer for this session. For Checkout Sessions in <code>payment</code> or <code>subscription</code> mode, Checkout will create a new customer object based on information provided during the session unless an existing customer was provided when the session was created.
  * @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 a session is complete, use the <code>customer</code> field.
  * @property \Stripe\StripeObject[] $display_items The line items, plans, or SKUs purchased by the customer.
+ * @property null|\Stripe\Collection $line_items The line items purchased by the customer. <a href="https://stripe.com/docs/api/expanding_objects">Expand</a> this field to include it in the response.
  * @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 key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
@@ -47,10 +48,27 @@ class Session extends \Stripe\ApiResource
 
     use \Stripe\ApiOperations\All;
     use \Stripe\ApiOperations\Create;
+    use \Stripe\ApiOperations\NestedResource;
     use \Stripe\ApiOperations\Retrieve;
 
     const SUBMIT_TYPE_AUTO = 'auto';
     const SUBMIT_TYPE_BOOK = 'book';
     const SUBMIT_TYPE_DONATE = 'donate';
     const SUBMIT_TYPE_PAY = 'pay';
+
+    const PATH_LINE_ITEMS = '/line_items';
+
+    /**
+     * @param string $id the ID of the session on which to retrieve the items
+     * @param null|array $params
+     * @param null|array|string $opts
+     *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
+     * @return \Stripe\Collection the list of items
+     */
+    public static function allLineItems($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_LINE_ITEMS, $params, $opts);
+    }
 }

lib/Customer.php

@@ -8,8 +8,9 @@
  * allows you to create, delete, and update your customers. You can retrieve
  * individual customers as well as a list of all your customers.
  *
- * Related guide: <a href="https://stripe.com/docs/saving-cards">Saving Cards with
- * Customers</a>.
+ * Related guide: <a
+ * href="https://stripe.com/docs/payments/save-during-payment">Save a card during
+ * payment</a>.
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.

lib/LineItem.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * Checkout Session line item.
+ *
+ * @property string $id Unique identifier for the object.
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property null|int $amount_subtotal Total before any discounts or taxes is applied.
+ * @property null|int $amount_total Total after discounts and taxes.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property string $description An arbitrary string attached to the object. Often useful for displaying to users. Defaults to product name.
+ * @property \Stripe\Price $price <p>Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme.</p><p>For example, you might have a single &quot;gold&quot; product that has prices for $10/month, $100/year, and €9 once.</p><p>Related guides: <a href="https://stripe.com/docs/billing/subscriptions/set-up-subscription">Set up a subscription</a>, <a href="https://stripe.com/docs/billing/invoices/create">create an invoice</a>, and more about <a href="https://stripe.com/docs/billing/prices-guide">products and prices</a>.</p>
+ * @property null|int $quantity The quantity of products being purchased.
+ * @property null|\Stripe\StripeObject[] $taxes The taxes applied to the line item.
+ */
+class LineItem extends ApiResource
+{
+    const OBJECT_NAME = 'item';
+
+    use ApiOperations\All;
+}

lib/Plan.php

@@ -23,8 +23,8 @@
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property bool $active Whether the plan can be used for new purchases.
  * @property null|string $aggregate_usage Specifies a usage aggregation strategy for plans of <code>usage_type=metered</code>. Allowed values are <code>sum</code> for summing up all usage during a period, <code>last_during_period</code> for using the last usage record reported within a period, <code>last_ever</code> for using the last usage record ever (across period bounds) or <code>max</code> which uses the usage record with the maximum reported usage during a period. Defaults to <code>sum</code>.
- * @property null|int $amount The amount in %s to be charged on the interval specified.
- * @property null|string $amount_decimal Same as <code>amount</code>, but contains a decimal value with at most 12 decimal places.
+ * @property null|int $amount The unit amount in %s to be charged, represented as a whole integer if possible.
+ * @property null|string $amount_decimal The unit amount in %s to be charged, represented as a decimal string with at most 12 decimal places.
  * @property string $billing_scheme Describes how to compute the price per period. Either <code>per_unit</code> or <code>tiered</code>. <code>per_unit</code> indicates that the fixed amount (specified in <code>amount</code>) will be charged per unit in <code>quantity</code> (for plans with <code>usage_type=licensed</code>), or per unit of total usage (for plans with <code>usage_type=metered</code>). <code>tiered</code> indicates that the unit pricing will be computed using a tiering strategy as defined using the <code>tiers</code> and <code>tiers_mode</code> attributes.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.

lib/Price.php

@@ -36,8 +36,8 @@
  * @property null|string $tiers_mode Defines if the tiering price should be <code>graduated</code> or <code>volume</code> based. In <code>volume</code>-based tiering, the maximum quantity within a period determines the per unit price. In <code>graduated</code> tiering, pricing can change as the quantity grows.
  * @property null|\Stripe\StripeObject $transform_quantity Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with <code>tiers</code>.
  * @property string $type One of <code>one_time</code> or <code>recurring</code> depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
- * @property null|int $unit_amount The unit amount in %s to be charged.
- * @property null|string $unit_amount_decimal Same as <code>amount</code>, but contains a decimal value with at most 12 decimal places.
+ * @property null|int $unit_amount The unit amount in %s to be charged, represented as a whole integer if possible.
+ * @property null|string $unit_amount_decimal The unit amount in %s to be charged, represented as a decimal string with at most 12 decimal places.
  */
 class Price extends ApiResource
 {

lib/Product.php

@@ -6,7 +6,7 @@
  * Products describe the specific goods or services you offer to your customers.
  * For example, you might offer a Standard and Premium version of your goods or
  * service; each version would be a separate Product. They can be used in
- * conjuction with <a href="https://stripe.com/docs/api#skus">SKUs</a> and <a
+ * conjunction with <a href="https://stripe.com/docs/api#skus">SKUs</a> and <a
  * href="https://stripe.com/docs/api#plans">Plans</a> to configure pricing in
  * Checkout and Subscriptions.
  *

lib/Util/ObjectTypes.php

@@ -48,6 +48,7 @@ class ObjectTypes
         \Stripe\Issuing\Cardholder::OBJECT_NAME => \Stripe\Issuing\Cardholder::class,
         \Stripe\Issuing\Dispute::OBJECT_NAME => \Stripe\Issuing\Dispute::class,
         \Stripe\Issuing\Transaction::OBJECT_NAME => \Stripe\Issuing\Transaction::class,
+        \Stripe\LineItem::OBJECT_NAME => \Stripe\LineItem::class,
         \Stripe\LoginLink::OBJECT_NAME => \Stripe\LoginLink::class,
         \Stripe\Mandate::OBJECT_NAME => \Stripe\Mandate::class,
         \Stripe\Order::OBJECT_NAME => \Stripe\Order::class,

tests/Stripe/Checkout/SessionTest.php

@@ -51,4 +51,15 @@ public function testIsRetrievable()
         $resource = Session::retrieve(self::TEST_RESOURCE_ID);
         static::assertInstanceOf(\Stripe\Checkout\Session::class, $resource);
     }
+
+    public function testCanListLineItems()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/checkout/sessions/' . self::TEST_RESOURCE_ID . '/line_items'
+        );
+        $resources = Session::allLineItems(self::TEST_RESOURCE_ID);
+        static::assertInternalType('array', $resources->data);
+        static::assertInstanceOf(\Stripe\LineItem::class, $resources->data[0]);
+    }
 }