Merge pull request #414 from recurly/api_version_2_20

Release version 2.12.3

Author: bhelx

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Recurly PHP Client Library CHANGELOG
 
+## Version 2.12.3 (May 21st, 2019)
+
+This brings us up to API version 2.20. There are no breaking changes
+
+* Add shipping fees [PR](https://github.com/recurly/recurly-client-php/pull/412)
+* Support updating a subscription at next bill date [PR](https://github.com/recurly/recurly-client-php/pull/413)
+
 ## Version 2.12.2 (April 26th, 2019)
 
 * Ensure nested resources have the same client as their parent [PR](https://github.com/recurly/recurly-client-php/pull/409)

lib/recurly.php

@@ -49,6 +49,9 @@
 require_once(dirname(__FILE__) . '/recurly/redemption_list.php');
 require_once(dirname(__FILE__) . '/recurly/shipping_address.php');
 require_once(dirname(__FILE__) . '/recurly/shipping_address_list.php');
+require_once(dirname(__FILE__) . '/recurly/shipping_fee.php');
+require_once(dirname(__FILE__) . '/recurly/shipping_method.php');
+require_once(dirname(__FILE__) . '/recurly/shipping_method_list.php');
 require_once(dirname(__FILE__) . '/recurly/subscription.php');
 require_once(dirname(__FILE__) . '/recurly/subscription_list.php');
 require_once(dirname(__FILE__) . '/recurly/subscription_addon.php');

lib/recurly/base.php

@@ -265,6 +265,9 @@ public function getLinks() {
     'setup_fee_in_cents' => 'Recurly_CurrencyList',
     'shipping_address' => 'Recurly_ShippingAddress',
     'shipping_addresses' => 'Recurly_ShippingAddressList',
+    'shipping_fee' => 'Recurly_ShippingFee',
+    'shipping_method' => 'Recurly_ShippingMethod',
+    'shipping_methods' => 'Recurly_ShippingMethodList',
     'subscription' => 'Recurly_Subscription',
     'subscriptions' => 'Recurly_SubscriptionList',
     'subscription_add_ons' => 'array',

lib/recurly/client.php

@@ -22,7 +22,7 @@ class Recurly_Client
   /**
    * API Version
    */
-  public static $apiVersion = '2.19';
+  public static $apiVersion = '2.20';
 
   /**
    * The path to your CA certs. Use only if needed (if you can't fix libcurl/php).
@@ -50,7 +50,7 @@ class Recurly_Client
   private static $apiUrl = 'https://%s.recurly.com/v2';
 
 
-  const API_CLIENT_VERSION = '2.12.2';
+  const API_CLIENT_VERSION = '2.12.3';
   const DEFAULT_ENCODING = 'UTF-8';
 
   const GET = 'GET';
@@ -74,6 +74,7 @@ class Recurly_Client
   const PATH_INVOICES = '/invoices';
   const PATH_NOTES = '/notes';
   const PATH_PLANS = '/plans';
+  const PATH_SHIPPING_METHOD = '/shipping_methods';
   const PATH_SUBSCRIPTIONS = '/subscriptions';
   const PATH_TRANSACTIONS = '/transactions';
   const PATH_MEASURED_UNITS = '/measured_units';

lib/recurly/purchase.php

@@ -2,19 +2,20 @@
 /**
  * Class Recurly_Purchase
  * @property Recurly_Account $account The account for the purchase. Can create an account or use existing.
- * @property Recurly_Adjustment[] $adjustments The array of adjustments for the purchase
- * @property string $collection_method The invoice collection method ('automatic' or 'manual')
- * @property string $currency The currency to use in this invoice
- * @property string $po_number The po number for the invoice
- * @property integer $net_terms The net terms of the invoice
- * @property string[] $coupon_codes An array of coupon codes to apply to the purchase
- * @property Recurly_Subscription[] $subscriptions An array of subscriptions to apply to the purchase
- * @property Recurly_GiftCard $gift_card A gift card to apply to the purchase
+ * @property Recurly_Adjustment[] $adjustments The array of adjustments for the purchase.
+ * @property string $collection_method The invoice collection method ('automatic' or 'manual').
+ * @property string $currency The currency to use in this invoice.
+ * @property string $po_number The po number for the invoice.
+ * @property integer $net_terms The net terms of the invoice.
+ * @property string[] $coupon_codes An array of coupon codes to apply to the purchase.
+ * @property Recurly_Subscription[] $subscriptions An array of subscriptions to apply to the purchase.
+ * @property Recurly_GiftCard $gift_card A gift card to apply to the purchase.
  * @property string $customer_notes Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.
  * @property string $terms_and_conditions Optional Terms and Conditions field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Custom notes will stay with a subscription on all renewals.
  * @property string $vat_reverse_charge_notes Optional VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Custom notes will stay with a subscription on all renewals.
  * @property integer $shipping_address_id Optional id of an existing ShippingAddress to be applied to all subscriptions and adjustments in purchase.
  * @property string $gateway_code Optional base36 encoded id for the gateway you wish to use for this transaction.
+ * @property Recurly_ShippingFee[] $shipping_fees Optional array of shipping fees to apply to the purchase.
  */
 class Recurly_Purchase extends Recurly_Resource
 {
@@ -115,7 +116,7 @@ protected function getWriteableAttributes() {
       'account', 'adjustments', 'collection_method', 'currency', 'po_number',
       'net_terms', 'subscriptions', 'gift_card', 'coupon_codes', 'customer_notes',
       'terms_and_conditions', 'vat_reverse_charge_notes', 'shipping_address_id',
-      'gateway_code'
+      'gateway_code', 'shipping_fees'
     );
   }
 }

lib/recurly/shipping_fee.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * Class Recurly_ShippingFee
+ * @property string $shipping_method_code Unique code to identify the shipping method.
+ * @property integer $shipping_amount_in_cents The amount of this shipping fee.
+ * @property Recurly_ShippingAddress $shipping_address Optional address this shipping fee is associated with.
+ * @property string $shipping_address_id Optional id of the existing shipping address this fee is associated with.
+ */
+class Recurly_ShippingFee extends Recurly_Resource
+{
+  protected function getNodeName() {
+    return 'shipping_fee';
+  }
+
+  protected function populateXmlDoc(&$doc, &$node, &$obj, $nested = false) {
+    if ($this->isEmbedded($node, 'shipping_fees')) {
+      $feeNode = $node->appendChild($doc->createElement($this->getNodeName()));
+      parent::populateXmlDoc($doc, $feeNode, $obj, $nested);
+    } else {
+      parent::populateXmlDoc($doc, $node, $obj, $nested);
+    }
+  }
+
+  protected function getWriteableAttributes() {
+    return array(
+      'shipping_method_code', 'shipping_amount_in_cents', 'shipping_address',
+      'shipping_address_id'
+    );
+  }
+}

lib/recurly/shipping_method.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * Class Recurly_ShippingMethod
+ * @property string $code Unique code to identify the shipping method.
+ * @property string $name The name of the shipping method.
+ * @property string $accounting_code The accounting code of the shipping method.
+ * @property string $tax_code The tax code of the shipping method.
+ * @property DateTime $created_at The date and time the shipping method was created.
+ * @property DateTime $updated_at The date and time the shipping method was last updated.
+ */
+class Recurly_ShippingMethod extends Recurly_Resource
+{
+  /**
+   * @param string $code The shipping method code
+   * @param Recurly_Client $client Optional client for the request, useful for mocking the client
+   * @return object Recurly_Resource or null
+   * @throws Recurly_Error
+   */
+  public static function get($code, $client = null) {
+    return Recurly_Base::_get(Recurly_ShippingMethod::uriForShippingMethod($code), $client);
+  }
+
+  protected function uri() {
+    if (!empty($this->_href))
+      return $this->getHref();
+    else
+      return Recurly_ShippingMethod::uriForShippingMethod($this->code);
+  }
+
+  protected static function uriForShippingMethod($code) {
+    return Recurly_Client::PATH_SHIPPING_METHOD . '/' . rawurlencode($code);
+  }
+
+  protected function getNodeName() {
+    return 'shipping_method';
+  }
+
+  protected function getWriteableAttributes() {
+    return array();
+  }
+}

lib/recurly/shipping_method_list.php

@@ -0,0 +1,13 @@
+<?php
+
+class Recurly_ShippingMethodList extends Recurly_Pager
+{
+  public static function get($params = null, $client = null) {
+    $uri = self::_uriWithParams(Recurly_Client::PATH_SHIPPING_METHOD, $params);
+    return new self($uri, $client);
+  }
+
+  protected function getNodeName() {
+    return 'shipping_methods';
+  }
+}

lib/recurly/subscription.php

@@ -43,6 +43,8 @@
  * @property string $uuid Subscription's unique identifier.
  * @property string $timeframe now for immediate, renewal to perform when the subscription renews. Defaults to now.
  * @property string $gateway_code The unique identifier of a payment gateway used to specify which payment gateway you wish to process this subscriptions’ payments
+ * @property string $shipping_method_code The unique identifier of the shipping method for this subscription.
+ * @property integer $shipping_amount_in_cents The amount charged for shipping in cents.
  */
 class Recurly_Subscription extends Recurly_Resource
 {
@@ -124,6 +126,15 @@ public function updateAtRenewal() {
     $this->_save(Recurly_Client::PUT, $this->uri());
   }
 
+  /**
+   * Make an update that applies at the next bill date of the subscription.
+   *
+   * @throws Recurly_Error
+   */
+  public function updateAtNextBillDate() {
+    $this->timeframe = 'bill_date';
+    $this->_save(Recurly_Client::PUT, $this->uri());
+  }
 
   /**
    * Terminate the subscription immediately and issue a full refund of the last renewal
@@ -267,7 +278,8 @@ protected function getWriteableAttributes() {
       'bank_account_authorized_at', 'revenue_schedule_type', 'gift_card',
       'shipping_address', 'shipping_address_id', 'imported_trial',
       'remaining_pause_cycles', 'custom_fields', 'auto_renew',
-      'renewal_billing_cycles', 'gateway_code'
+      'renewal_billing_cycles', 'gateway_code', 'shipping_method_code',
+      'shipping_amount_in_cents'
     );
   }
 }