You are here

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

class Braintree_Address in Commerce Braintree 7

Creates and manages Braintree Addresses

An Address belongs to a Customer. It can be associated to a CreditCard as the billing address. It can also be used as the shipping address when creating a Transaction.

@package Braintree @copyright 2010 Braintree Payment Solutions

@property-read string $company @property-read string $countryName @property-read string $createdAt @property-read string $customerId @property-read string $extendedAddress @property-read string $firstName @property-read string $id @property-read string $lastName @property-read string $locality @property-read string $postalCode @property-read string $region @property-read string $streetAddress @property-read string $updatedAt

Hierarchy

Expanded class hierarchy of Braintree_Address

File

braintree_php/lib/Braintree/Address.php, line 34

View source 
class Braintree_Address extends Braintree {

  /* public class methods */

  /**
   *
   * @access public
   * @param  array  $attribs
   * @return object Result, either Successful or Error
   */
  public static function create($attribs) {
    Braintree_Util::verifyKeys(self::createSignature(), $attribs);
    $customerId = isset($attribs['customerId']) ? $attribs['customerId'] : null;
    self::_validateCustomerId($customerId);
    unset($attribs['customerId']);
    return self::_doCreate('/customers/' . $customerId . '/addresses', array(
      'address' => $attribs,
    ));
  }

  /**
   * attempts the create operation assuming all data will validate
   * returns a Braintree_Address object instead of a Result
   *
   * @access public
   * @param  array $attribs
   * @return object
   * @throws Braintree_Exception_ValidationError
   */
  public static function createNoValidate($attribs) {
    $result = self::create($attribs);
    return self::returnObjectOrThrowException(__CLASS__, $result);
  }

  /**
   * delete an address by id
   *
   * @param mixed $customerOrId
   * @param string $addressId
   */
  public static function delete($customerOrId = null, $addressId = null) {
    self::_validateId($addressId);
    $customerId = self::_determineCustomerId($customerOrId);
    Braintree_Http::delete('/customers/' . $customerId . '/addresses/' . $addressId);
    return new Braintree_Result_Successful();
  }

  /**
   * find an address by id
   *
   * Finds the address with the given <b>addressId</b> that is associated
   * to the given <b>customerOrId</b>.
   * If the address cannot be found, a NotFound exception will be thrown.
   *
   *
   * @access public
   * @param mixed $customerOrId
   * @param string $addressId
   * @return object Braintree_Address
   * @throws Braintree_Exception_NotFound
   */
  public static function find($customerOrId, $addressId) {
    $customerId = self::_determineCustomerId($customerOrId);
    self::_validateId($addressId);
    try {
      $response = Braintree_Http::get('/customers/' . $customerId . '/addresses/' . $addressId);
      return self::factory($response['address']);
    } catch (Braintree_Exception_NotFound $e) {
      throw new Braintree_Exception_NotFound('address for customer ' . $customerId . ' with id ' . $addressId . ' not found.');
    }
  }

  /**
   * returns false if comparing object is not a Braintree_Address,
   * or is a Braintree_Address with a different id
   *
   * @param object $other address to compare against
   * @return boolean
   */
  public function isEqual($other) {
    return !$other instanceof Braintree_Address ? false : $this->id === $other->id && $this->customerId === $other->customerId;
  }

  /**
   * updates the address record
   *
   * if calling this method in static context,
   * customerOrId is the 2nd attribute, addressId 3rd.
   * customerOrId & addressId are not sent in object context.
   *
   *
   * @access public
   * @param array $attributes
   * @param mixed $customerOrId (only used in static call)
   * @param string $addressId (only used in static call)
   * @return object Braintree_Result_Successful or Braintree_Result_Error
   */
  public static function update($customerOrId, $addressId, $attributes) {
    self::_validateId($addressId);
    $customerId = self::_determineCustomerId($customerOrId);
    Braintree_Util::verifyKeys(self::updateSignature(), $attributes);
    $response = Braintree_Http::put('/customers/' . $customerId . '/addresses/' . $addressId, array(
      'address' => $attributes,
    ));
    return self::_verifyGatewayResponse($response);
  }

  /**
   * update an address record, assuming validations will pass
   *
   * if calling this method in static context,
   * customerOrId is the 2nd attribute, addressId 3rd.
   * customerOrId & addressId are not sent in object context.
   *
   * @access public
   * @param array $transactionAttribs
   * @param string $customerId
   * @return object Braintree_Transaction
   * @throws Braintree_Exception_ValidationsFailed
   * @see Braintree_Address::update()
   */
  public static function updateNoValidate($customerOrId, $addressId, $attributes) {
    $result = self::update($customerOrId, $addressId, $attributes);
    return self::returnObjectOrThrowException(__CLASS__, $result);
  }

  /**
   * creates a full array signature of a valid create request
   * @return array gateway create request format
   */
  public static function createSignature() {
    return array(
      'company',
      'countryCodeAlpha2',
      'countryCodeAlpha3',
      'countryCodeNumeric',
      'countryName',
      'customerId',
      'extendedAddress',
      'firstName',
      'lastName',
      'locality',
      'postalCode',
      'region',
      'streetAddress',
    );
  }

  /**
   * creates a full array signature of a valid update request
   * @return array gateway update request format
   */
  public static function updateSignature() {

    // TODO: remove customerId from update signature
    return self::createSignature();
  }

  /**
   * create a printable representation of the object as:
   * ClassName[property=value, property=value]
   * @ignore
   * @return var
   */
  public function __toString() {
    return __CLASS__ . '[' . Braintree_Util::attributesToString($this->_attributes) . ']';
  }

  /**
   * sets instance properties from an array of values
   *
   * @ignore
   * @access protected
   * @param array $addressAttribs array of address data
   * @return none
   */
  protected function _initialize($addressAttribs) {

    // set the attributes
    $this->_attributes = $addressAttribs;
  }

  /**
   * verifies that a valid address id is being used
   * @ignore
   * @param string $id address id
   * @throws InvalidArgumentException
   */
  private static function _validateId($id = null) {
    if (empty($id) || trim($id) == "") {
      throw new InvalidArgumentException('expected address id to be set');
    }
    if (!preg_match('/^[0-9A-Za-z_-]+$/', $id)) {
      throw new InvalidArgumentException($id . ' is an invalid address id.');
    }
  }

  /**
   * verifies that a valid customer id is being used
   * @ignore
   * @param string $id customer id
   * @throws InvalidArgumentException
   */
  private static function _validateCustomerId($id = null) {
    if (empty($id) || trim($id) == "") {
      throw new InvalidArgumentException('expected customer id to be set');
    }
    if (!preg_match('/^[0-9A-Za-z_-]+$/', $id)) {
      throw new InvalidArgumentException($id . ' is an invalid customer id.');
    }
  }

  /**
   * determines if a string id or Customer object was passed
   * @ignore
   * @param mixed $customerOrId
   * @return string customerId
   */
  private static function _determineCustomerId($customerOrId) {
    $customerId = $customerOrId instanceof Braintree_Customer ? $customerOrId->id : $customerOrId;
    self::_validateCustomerId($customerId);
    return $customerId;
  }

  /* private class methods */

  /**
   * sends the create request to the gateway
   * @ignore
   * @param string $url
   * @param array $params
   * @return mixed
   */
  private static function _doCreate($url, $params) {
    $response = Braintree_Http::post($url, $params);
    return self::_verifyGatewayResponse($response);
  }

  /**
   * generic method for validating incoming gateway responses
   *
   * creates a new Braintree_Address object and encapsulates
   * it inside a Braintree_Result_Successful object, or
   * encapsulates a Braintree_Errors object inside a Result_Error
   * alternatively, throws an Unexpected exception if the response is invalid.
   *
   * @ignore
   * @param array $response gateway response values
   * @return object Result_Successful or Result_Error
   * @throws Braintree_Exception_Unexpected
   */
  private static function _verifyGatewayResponse($response) {
    if (isset($response['address'])) {

      // return a populated instance of Braintree_Address
      return new Braintree_Result_Successful(self::factory($response['address']));
    }
    else {
      if (isset($response['apiErrorResponse'])) {
        return new Braintree_Result_Error($response['apiErrorResponse']);
      }
      else {
        throw new Braintree_Exception_Unexpected("Expected address or apiErrorResponse");
      }
    }
  }

  /**
   *  factory method: returns an instance of Braintree_Address
   *  to the requesting method, with populated properties
   * @ignore
   * @return object instance of Braintree_Address
   */
  public static function factory($attributes) {
    $instance = new self();
    $instance
      ->_initialize($attributes);
    return $instance;
  }

}

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_Address::create public static function @access public
Braintree_Address::createNoValidate public static function attempts the create operation assuming all data will validate returns a Braintree_Address object instead of a Result
Braintree_Address::createSignature public static function creates a full array signature of a valid create request
Braintree_Address::delete public static function delete an address by id
Braintree_Address::factory public static function factory method: returns an instance of Braintree_Address to the requesting method, with populated properties @ignore
Braintree_Address::find public static function find an address by id
Braintree_Address::isEqual public function returns false if comparing object is not a Braintree_Address, or is a Braintree_Address with a different id
Braintree_Address::update public static function updates the address record
Braintree_Address::updateNoValidate public static function update an address record, assuming validations will pass
Braintree_Address::updateSignature public static function creates a full array signature of a valid update request
Braintree_Address::_determineCustomerId private static function determines if a string id or Customer object was passed @ignore
Braintree_Address::_doCreate private static function sends the create request to the gateway @ignore
Braintree_Address::_initialize protected function sets instance properties from an array of values
Braintree_Address::_validateCustomerId private static function verifies that a valid customer id is being used @ignore
Braintree_Address::_validateId private static function verifies that a valid address id is being used @ignore
Braintree_Address::_verifyGatewayResponse private static function generic method for validating incoming gateway responses
Braintree_Address::__toString public function create a printable representation of the object as: ClassName[property=value, property=value] @ignore