You are here

Home » API reference » Commerce Braintree 7 » Subscription.php

class Braintree_Subscription in Commerce Braintree 7

Braintree Subscription module

<b>== More information ==</b>

For more detailed information on Subscriptions, see {@link http://www.braintreepayments.com/gateway/subscription-api http://www.braintreepaymentsolutions.com/gateway/subscription-api}

PHP Version 5

@package Braintree @copyright 2010 Braintree Payment Solutions

Hierarchy

Expanded class hierarchy of Braintree_Subscription

File

braintree_php/lib/Braintree/Subscription.php, line 14

View source 
class Braintree_Subscription extends Braintree {
  const ACTIVE = 'Active';
  const CANCELED = 'Canceled';
  const EXPIRED = 'Expired';
  const PAST_DUE = 'Past Due';
  const PENDING = 'Pending';
  public static function create($attributes) {
    Braintree_Util::verifyKeys(self::_createSignature(), $attributes);
    $response = Braintree_Http::post('/subscriptions', array(
      'subscription' => $attributes,
    ));
    return self::_verifyGatewayResponse($response);
  }

  /**
   * @ignore
   */
  public static function factory($attributes) {
    $instance = new self();
    $instance
      ->_initialize($attributes);
    return $instance;
  }
  public static function find($id) {
    self::_validateId($id);
    try {
      $response = Braintree_Http::get('/subscriptions/' . $id);
      return self::factory($response['subscription']);
    } catch (Braintree_Exception_NotFound $e) {
      throw new Braintree_Exception_NotFound('subscription with id ' . $id . ' not found');
    }
  }
  public static function search($query) {
    $criteria = array();
    foreach ($query as $term) {
      $criteria[$term->name] = $term
        ->toparam();
    }
    $response = braintree_http::post('/subscriptions/advanced_search_ids', array(
      'search' => $criteria,
    ));
    $pager = array(
      'className' => __CLASS__,
      'classMethod' => 'fetch',
      'methodArgs' => array(
        $query,
      ),
    );
    return new Braintree_ResourceCollection($response, $pager);
  }
  public static function fetch($query, $ids) {
    $criteria = array();
    foreach ($query as $term) {
      $criteria[$term->name] = $term
        ->toparam();
    }
    $criteria["ids"] = Braintree_SubscriptionSearch::ids()
      ->in($ids)
      ->toparam();
    $response = Braintree_Http::post('/subscriptions/advanced_search', array(
      'search' => $criteria,
    ));
    return Braintree_Util::extractAttributeAsArray($response['subscriptions'], 'subscription');
  }
  public static function update($subscriptionId, $attributes) {
    Braintree_Util::verifyKeys(self::_updateSignature(), $attributes);
    $response = Braintree_Http::put('/subscriptions/' . $subscriptionId, array(
      'subscription' => $attributes,
    ));
    return self::_verifyGatewayResponse($response);
  }
  public static function retryCharge($subscriptionId, $amount = null) {
    $transaction_params = array(
      'type' => Braintree_Transaction::SALE,
      'subscriptionId' => $subscriptionId,
    );
    if (isset($amount)) {
      $transaction_params['amount'] = $amount;
    }
    $response = Braintree_Http::post('/transactions', array(
      'transaction' => $transaction_params,
    ));
    return self::_verifyGatewayResponse($response);
  }
  public static function cancel($subscriptionId) {
    $response = Braintree_Http::put('/subscriptions/' . $subscriptionId . '/cancel');
    return self::_verifyGatewayResponse($response);
  }
  private static function _createSignature() {
    return array_merge(array(
      'billingDayOfMonth',
      'firstBillingDate',
      'id',
      'merchantAccountId',
      'neverExpires',
      'numberOfBillingCycles',
      'paymentMethodToken',
      'planId',
      'price',
      'trialDuration',
      'trialDurationUnit',
      'trialPeriod',
      array(
        'descriptor' => array(
          'name',
          'phone',
        ),
      ),
      array(
        'options' => array(
          'doNotInheritAddOnsOrDiscounts',
          'startImmediately',
        ),
      ),
    ), self::_addOnDiscountSignature());
  }
  private static function _updateSignature() {
    return array_merge(array(
      'merchantAccountId',
      'numberOfBillingCycles',
      'paymentMethodToken',
      'planId',
      'id',
      'neverExpires',
      'price',
      array(
        'descriptor' => array(
          'name',
          'phone',
        ),
      ),
      array(
        'options' => array(
          'prorateCharges',
          'replaceAllAddOnsAndDiscounts',
          'revertSubscriptionOnProrationFailure',
        ),
      ),
    ), self::_addOnDiscountSignature());
  }
  private static function _addOnDiscountSignature() {
    return array(
      array(
        'addOns' => array(
          array(
            'add' => array(
              'amount',
              'inheritedFromId',
              'neverExpires',
              'numberOfBillingCycles',
              'quantity',
            ),
          ),
          array(
            'update' => array(
              'amount',
              'existingId',
              'neverExpires',
              'numberOfBillingCycles',
              'quantity',
            ),
          ),
          array(
            'remove' => array(
              '_anyKey_',
            ),
          ),
        ),
      ),
      array(
        'discounts' => array(
          array(
            'add' => array(
              'amount',
              'inheritedFromId',
              'neverExpires',
              'numberOfBillingCycles',
              'quantity',
            ),
          ),
          array(
            'update' => array(
              'amount',
              'existingId',
              'neverExpires',
              'numberOfBillingCycles',
              'quantity',
            ),
          ),
          array(
            'remove' => array(
              '_anyKey_',
            ),
          ),
        ),
      ),
    );
  }

  /**
   * @ignore
   */
  protected function _initialize($attributes) {
    $this->_attributes = $attributes;
    $addOnArray = array();
    if (isset($attributes['addOns'])) {
      foreach ($attributes['addOns'] as $addOn) {
        $addOnArray[] = Braintree_AddOn::factory($addOn);
      }
    }
    $this->_attributes['addOns'] = $addOnArray;
    $discountArray = array();
    if (isset($attributes['discounts'])) {
      foreach ($attributes['discounts'] as $discount) {
        $discountArray[] = Braintree_Discount::factory($discount);
      }
    }
    $this->_attributes['discounts'] = $discountArray;
    if (isset($attributes['descriptor'])) {
      $this
        ->_set('descriptor', new Braintree_Descriptor($attributes['descriptor']));
    }
    $transactionArray = array();
    if (isset($attributes['transactions'])) {
      foreach ($attributes['transactions'] as $transaction) {
        $transactionArray[] = Braintree_Transaction::factory($transaction);
      }
    }
    $this->_attributes['transactions'] = $transactionArray;
  }

  /**
   * @ignore
   */
  private static function _validateId($id = null) {
    if (empty($id)) {
      throw new InvalidArgumentException('expected subscription id to be set');
    }
    if (!preg_match('/^[0-9A-Za-z_-]+$/', $id)) {
      throw new InvalidArgumentException($id . ' is an invalid subscription id.');
    }
  }

  /**
   * @ignore
   */
  private static function _verifyGatewayResponse($response) {
    if (isset($response['subscription'])) {
      return new Braintree_Result_Successful(self::factory($response['subscription']));
    }
    else {
      if (isset($response['transaction'])) {

        // return a populated instance of Braintree_Transaction, for subscription retryCharge
        return new Braintree_Result_Successful(Braintree_Transaction::factory($response['transaction']));
      }
      else {
        if (isset($response['apiErrorResponse'])) {
          return new Braintree_Result_Error($response['apiErrorResponse']);
        }
        else {
          throw new Braintree_Exception_Unexpected("Expected subscription, transaction, or apiErrorResponse");
        }
      }
    }
  }

  /**
   * returns a string representation of the customer
   * @return string
   */
  public function __toString() {
    return __CLASS__ . '[' . Braintree_Util::attributesToString($this->_attributes) . ']';
  }

}

Members

Namesort descending Modifiers Type Description Overrides
Braintree::returnObjectOrThrowException public static function
Braintree::_set public function
Braintree::__clone protected function @ignore don't permit cloning the instances (like $x = clone $v)
Braintree::__construct protected function @ignore don't permit an explicit call of the constructor! (like $t = new Braintree_Transaction()) 1
Braintree::__get public function returns private/nonexistent instance properties @ignore @access public
Braintree::__isset public function used by isset() and empty() @access public
Braintree_Subscription::ACTIVE constant
Braintree_Subscription::cancel public static function
Braintree_Subscription::CANCELED constant
Braintree_Subscription::create public static function
Braintree_Subscription::EXPIRED constant
Braintree_Subscription::factory public static function @ignore
Braintree_Subscription::fetch public static function
Braintree_Subscription::find public static function
Braintree_Subscription::PAST_DUE constant
Braintree_Subscription::PENDING constant
Braintree_Subscription::retryCharge public static function
Braintree_Subscription::search public static function
Braintree_Subscription::update public static function
Braintree_Subscription::_addOnDiscountSignature private static function
Braintree_Subscription::_createSignature private static function
Braintree_Subscription::_initialize protected function @ignore
Braintree_Subscription::_updateSignature private static function
Braintree_Subscription::_validateId private static function @ignore
Braintree_Subscription::_verifyGatewayResponse private static function @ignore
Braintree_Subscription::__toString public function returns a string representation of the customer