Merge pull request #924 from stripe/remi/codegen-f75fd88

Add support for the `Price` resource and APIs

.travis.yml

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

init.php

@@ -112,6 +112,7 @@
 require __DIR__ . '/lib/Payout.php';
 require __DIR__ . '/lib/Person.php';
 require __DIR__ . '/lib/Plan.php';
+require __DIR__ . '/lib/Price.php';
 require __DIR__ . '/lib/Product.php';
 require __DIR__ . '/lib/Radar/EarlyFraudWarning.php';
 require __DIR__ . '/lib/Radar/ValueList.php';

lib/Checkout/Session.php

@@ -27,7 +27,7 @@
  * @property null|string $client_reference_id A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.
  * @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 null|\Stripe\StripeObject[] $display_items The line items, plans, or SKUs purchased by the customer.
+ * @property \Stripe\StripeObject[] $display_items The line items, plans, or SKUs 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 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.

lib/InvoiceItem.php

@@ -25,6 +25,7 @@
  * @property \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.
  * @property \Stripe\StripeObject $period
  * @property null|\Stripe\Plan $plan If the invoice item is a proration, the plan of the subscription that the proration was computed for.
+ * @property null|\Stripe\Price $price The price of the invoice item.
  * @property bool $proration Whether the invoice item was created automatically as a proration adjustment when the customer switched plans.
  * @property int $quantity Quantity of units for the invoice item. If the invoice item is a proration, the quantity of the subscription that the proration was computed for.
  * @property null|string|\Stripe\Subscription $subscription The subscription that this invoice item has been created for, if any.

lib/InvoiceLineItem.php

@@ -14,6 +14,7 @@
  * @property \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. Note that for line items with <code>type=subscription</code> this will reflect the metadata of the subscription that caused the line item to be created.
  * @property \Stripe\StripeObject $period
  * @property null|\Stripe\Plan $plan The plan of the subscription, if the line item is a subscription or a proration.
+ * @property null|\Stripe\Price $price The price of the line item.
  * @property bool $proration Whether this is a proration.
  * @property null|int $quantity The quantity of the subscription, if the line item is a subscription or a proration.
  * @property null|string $subscription The subscription that the invoice item pertains to, if any.

lib/Plan.php

@@ -3,9 +3,15 @@
 namespace Stripe;
 
 /**
- * Plans define the base price, currency, and billing cycle for subscriptions. For
- * example, you might have a $5/month plan that provides limited access to your
- * products, and a $15/month plan that allows full access.
+ * Plans define the base price, currency, and billing cycle for recurring purchases
+ * of products. Products help you track inventory or provisioning, and plans help
+ * you track pricing. Different physical goods or levels of service should be
+ * represented by products, and pricing options should be represented by plans.
+ * This approach lets you change prices without having to change your provisioning
+ * scheme.
+ *
+ * For example, you might have a single "gold" product that has plans for
+ * $10/month, $100/year, €9/month, and €90/year.
  *
  * Related guides: <a
  * href="https://stripe.com/docs/billing/subscriptions/set-up-subscription">Set up

lib/Price.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * 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.
+ *
+ * For example, you might have a single &quot;gold&quot; product that has prices
+ * for $10/month, $100/year, and €9 once.
+ *
+ * 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>.
+ *
+ * @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 bool $active Whether the price can be used for new purchases.
+ * @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>unit_amount</code> or <code>unit_amount_decimal</code>) will be charged per unit in <code>quantity</code> (for prices with <code>usage_type=licensed</code>), or per unit of total usage (for prices 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>.
+ * @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 $lookup_key A lookup key used to retrieve prices dynamically from a static string.
+ * @property \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.
+ * @property null|string $nickname A brief description of the plan, hidden from customers.
+ * @property string|\Stripe\Product $product The ID of the product this price is associated with.
+ * @property null|\Stripe\StripeObject $recurring The recurring components of a price such as <code>interval</code> and <code>usage_type</code>.
+ * @property null|\Stripe\StripeObject[] $tiers Each element represents a pricing tier. This parameter requires <code>billing_scheme</code> to be set to <code>tiered</code>. See also the documentation for <code>billing_scheme</code>.
+ * @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.
+ */
+class Price extends ApiResource
+{
+    const OBJECT_NAME = 'price';
+
+    use ApiOperations\All;
+    use ApiOperations\Create;
+    use ApiOperations\Retrieve;
+    use ApiOperations\Update;
+
+    const BILLING_SCHEME_PER_UNIT = 'per_unit';
+    const BILLING_SCHEME_TIERED = 'tiered';
+
+    const TIERS_MODE_GRADUATED = 'graduated';
+    const TIERS_MODE_VOLUME = 'volume';
+
+    const TYPE_ONE_TIME = 'one_time';
+    const TYPE_RECURRING = 'recurring';
+}

lib/Product.php

@@ -3,17 +3,20 @@
 namespace Stripe;
 
 /**
- * Store representations of products you sell in <code>Product</code> objects, used
- * in conjunction with <a href="https://stripe.com/docs/api#skus">SKUs</a>.
- * Products may be physical goods, to be shipped, or digital.
+ * 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
+ * href="https://stripe.com/docs/api#plans">Plans</a> to configure pricing in
+ * Checkout and Subscriptions.
  *
- * Documentation on <code>Product</code>s for use with <code>Subscription</code>s
- * can be found at <a
- * href="https://stripe.com/docs/api#service_products">Subscription Products</a>.
- *
- * Related guide: <a
- * href="https://stripe.com/docs/orders#define-products-skus">Define products and
- * SKUs</a>
+ * Related guides: <a
+ * href="https://stripe.com/docs/billing/subscriptions/set-up-subscription">Set up
+ * a subscription</a> or accept <a
+ * href="https://stripe.com/docs/payments/checkout/client#create-products">one-time
+ * payments with Checkout</a> and more about <a
+ * href="https://stripe.com/docs/billing/subscriptions/products-and-plans">Products
+ * and Plans</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/SubscriptionItem.php

@@ -11,7 +11,8 @@
  * @property null|\Stripe\StripeObject $billing_thresholds Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property \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.
- * @property \Stripe\Plan $plan <p>Plans define the base price, currency, and billing cycle for subscriptions. For example, you might have a $5/month plan that provides limited access to your products, and a $15/month plan that allows full access.</p><p>Related guides: <a href="https://stripe.com/docs/billing/subscriptions/set-up-subscription">Set up a subscription</a> and more about <a href="https://stripe.com/docs/billing/subscriptions/products-and-plans">products and plans</a>.</p>
+ * @property \Stripe\Plan $plan <p>Plans define the base price, currency, and billing cycle for recurring purchases of products. Products help you track inventory or provisioning, and plans help you track pricing. Different physical goods or levels of service should be represented by products, and pricing options should be represented by plans. 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 plans for $10/month, $100/year, €9/month, and €90/year.</p><p>Related guides: <a href="https://stripe.com/docs/billing/subscriptions/set-up-subscription">Set up a subscription</a> and more about <a href="https://stripe.com/docs/billing/subscriptions/products-and-plans">products and plans</a>.</p>
+ * @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 int $quantity The <a href="https://stripe.com/docs/subscriptions/quantities">quantity</a> of the plan to which the customer should be subscribed.
  * @property string $subscription The <code>subscription</code> this <code>subscription_item</code> belongs to.
  * @property null|\Stripe\TaxRate[] $tax_rates The tax rates which apply to this <code>subscription_item</code>. When set, the <code>default_tax_rates</code> on the subscription do not apply to this <code>subscription_item</code>.

lib/Util/ObjectTypes.php

@@ -58,6 +58,7 @@ class ObjectTypes
         \Stripe\Payout::OBJECT_NAME => \Stripe\Payout::class,
         \Stripe\Person::OBJECT_NAME => \Stripe\Person::class,
         \Stripe\Plan::OBJECT_NAME => \Stripe\Plan::class,
+        \Stripe\Price::OBJECT_NAME => \Stripe\Price::class,
         \Stripe\Product::OBJECT_NAME => \Stripe\Product::class,
         \Stripe\Radar\EarlyFraudWarning::OBJECT_NAME => \Stripe\Radar\EarlyFraudWarning::class,
         \Stripe\Radar\ValueList::OBJECT_NAME => \Stripe\Radar\ValueList::class,

tests/Stripe/PriceTest.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * @internal
+ * @covers \Stripe\Price
+ */
+final class PriceTest extends \PHPUnit\Framework\TestCase
+{
+    use TestHelper;
+
+    const TEST_RESOURCE_ID = 'price_123';
+
+    public function testIsListable()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/prices'
+        );
+        $resources = Price::all();
+        static::assertInternalType('array', $resources->data);
+        static::assertInstanceOf(\Stripe\Price::class, $resources->data[0]);
+    }
+
+    public function testIsRetrievable()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/prices/' . self::TEST_RESOURCE_ID
+        );
+        $resource = Price::retrieve(self::TEST_RESOURCE_ID);
+        static::assertInstanceOf(\Stripe\Price::class, $resource);
+    }
+
+    public function testIsCreatable()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/prices'
+        );
+        $resource = Price::create([
+            'unit_amount' => 2000,
+            'currency' => 'usd',
+            'recurring' => [
+                'interval' => 'month',
+            ],
+            'product_data' => [
+                'name' => 'Product Name',
+            ],
+        ]);
+        static::assertInstanceOf(\Stripe\Price::class, $resource);
+    }
+
+    public function testIsSaveable()
+    {
+        $resource = Price::retrieve(self::TEST_RESOURCE_ID);
+        $resource->metadata['key'] = 'value';
+        $this->expectsRequest(
+            'post',
+            '/v1/prices/' . $resource->id
+        );
+        $resource->save();
+        static::assertInstanceOf(\Stripe\Price::class, $resource);
+    }
+
+    public function testIsUpdatable()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/prices/' . self::TEST_RESOURCE_ID
+        );
+        $resource = Price::update(self::TEST_RESOURCE_ID, [
+            'metadata' => ['key' => 'value'],
+        ]);
+        static::assertInstanceOf(\Stripe\Price::class, $resource);
+    }
+}

tests/bootstrap.php

@@ -2,7 +2,7 @@
 
 require_once __DIR__ . '/StripeMock.php';
 
-\define('MOCK_MINIMUM_VERSION', '0.88.0');
+\define('MOCK_MINIMUM_VERSION', '0.89.0');
 
 if (\Stripe\StripeMock::start()) {
     \register_shutdown_function('\Stripe\StripeMock::stop');