You are here

Home » API reference » Ubercart Addresses 6.2 » UcAddressesAddress.class.php

class UcAddressesAddress in Ubercart Addresses 6.2

Same name and namespace in other branches
  1. 7 class/UcAddressesAddress.class.php \UcAddressesAddress

The main address class used by uc_addresses (and extension modules).

This is the main address class used by Ubercart Addresses. It's goal is to provide specific address book features, such as an address nickname and flags for being the default shipping and/or the default billing address.

Each instance is created through the address book, so the address book is able to keep track of all the addresses it contains.

The class extends UcAddressesSchemaAddress.

Hierarchy

Expanded class hierarchy of UcAddressesAddress

File

class/UcAddressesAddress.class.php, line 20
Contains the UcAddressesAddress class.

View source 
class UcAddressesAddress extends UcAddressesSchemaAddress {

  // -----------------------------------------------------------------------------
  // STATIC PROPERTIES
  // -----------------------------------------------------------------------------

  /**
   * Which ID a new address will get when constructed.
   *
   * This value will be decreased with 1 every time
   * a new address is constructed.
   * A new address in this case is an address not coming
   * from the database.
   *
   * @var int
   * @access private
   * @static
   */
  private static $nextNewAid = -1;

  // -----------------------------------------------------------------------------
  // PROPERTIES
  // -----------------------------------------------------------------------------

  /**
   * The address book the address belongs to.
   *
   * @var UcAddressesAddressBook
   * @access private
   */
  private $addressBook = NULL;

  // -----------------------------------------------------------------------------
  // CONSTRUCT
  // -----------------------------------------------------------------------------

  /**
   * UcAddressesAddress object constructor.
   *
   * @param UcAddressesAddressBook $addressBook
   *   An instance of UcAddressesAddressBook.
   * @param object $schemaAddress
   *   Values to fill the address with.
   *
   * @access public
   * @return void
   */
  public function __construct(UcAddressesAddressBook $addressBook, $schemaAddress = NULL) {
    parent::__construct($schemaAddress);
    $this->addressBook = $addressBook;
    if (!is_object($schemaAddress) || !$schemaAddress->aid) {

      // We always need an ID.
      $this
        ->getSchemaAddress()->aid = self::$nextNewAid--;
    }

    // Set other given values.
    if ($schemaAddress) {
      foreach ($schemaAddress as $fieldName => $value) {
        $this
          ->privSetUcAddressField($fieldName, $value);
      }
    }
    if ($this
      ->getSchemaAddress()->aid > 0) {

      // If an address is just loaded, mark this instance as 'clean' (= unchanged).
      $this
        ->clearDirty();
    }

    // All addresses need to be contained by an address book.
    $addressBook
      ->addAddress($this);
  }

  /**
   * Tells which members may kept when the address is being serialized.
   *
   * @access public
   * @return array
   *   An array of members to keep upon serialization.
   */
  public function __sleep() {
    $this
      ->getSchemaAddress()->uid = $this
      ->getUserId();
    return parent::__sleep();
  }

  /**
   * Restore variables when the address is unserialized.
   *
   * @access public
   * @return void
   */
  public function __wakeup() {
    parent::__wakeup();
    $this->addressBook = UcAddressesAddressBook::get($this
      ->getSchemaAddress()->uid);
    if ($this
      ->getId() <= self::$nextNewAid) {
      self::$nextNewAid = $this
        ->getId() - 1;
    }
    try {
      $this->addressBook
        ->addAddress($this);
    } catch (UcAddressesException $e) {

      // Ignore any exceptions.
    }
  }

  /**
   * Create a new unowned address.
   *
   * This method will create an empty address without an owner.
   * This is useful when you want to ask an anonymous user for an address
   * (e.g., when registering).
   * However, unonwed addresses can not be saved. In order to save this
   * address, the UcAddressesAddress method setOwner() should be called.
   *
   * @access public
   * @static
   * @return UcAddressesAddress
   *   A new instance of UcAddressesAddress.
   */
  public static function newAddress() {
    return UcAddressesAddressBook::newAddress();
  }

  /**
   * Make a copy of this address.
   *
   * This method only copies the aggregrated schema object over.
   * The fields aid, address_name, default_shipping and default_billing
   * will be emptied.
   *
   * @param UcAddressesAddressBook $addressBook
   *   (optional) The address book to copy the address to.
   *   Defaults to the address book the current address belongs to.
   *
   * @access public
   * @return UcAddressesAddress
   *   A new instance of UcAddressesAddress.
   */
  public function copyAddress(UcAddressesAddressBook $addressBook = NULL) {
    if (!$addressBook) {
      $addressBook = $this->addressBook;
    }

    // Get a copy of our schema address and empty the fields aid,
    // address_name, default_shipping and default_billing.
    $schemaAddress = clone $this
      ->getSchemaAddress();
    $schemaAddress->aid = 0;
    $schemaAddress->address_name = '';
    $schemaAddress->default_shipping = 0;
    $schemaAddress->default_billing = 0;
    $schemaAddress->uid = $addressBook
      ->getUserId();

    // Create a new address.
    $address = new UcAddressesAddress($addressBook, $schemaAddress);
    return $address;
  }

  // -----------------------------------------------------------------------------
  // ADDRESS METHODS
  // -----------------------------------------------------------------------------

  /**
   * Returns the address book the address is in.
   *
   * @access public
   * @return UcAddressesAddressBook
   *   The address book attached to this address.
   */
  public function getAddressBook() {
    return $this->addressBook;
  }

  /**
   * Returns address ID.
   *
   * @access public
   * @return int
   *   The address ID.
   */
  public function getId() {
    return $this
      ->getSchemaAddress()->aid;
  }

  /**
   * Alias of getId().
   *
   * @return int
   *   The address ID.
   * @see entity_id()
   */
  public function identifier() {
    return $this
      ->getId();
  }

  /**
   * Returns owner of this address.
   *
   * @access public
   * @return int
   *   ID of the owner of this address.
   */
  public function getUserId() {
    return $this->addressBook
      ->getUserId();
  }

  /**
   * Checks if the address is owned by an user.
   *
   * An address is owned by an user if the owner's user id
   * is not zero (= anonymous user).
   *
   * @access public
   * @return boolean
   *   TRUE if the address is owned.
   *   FALSE otherwise.
   */
  public function isOwned() {
    return $this
      ->getUserId() > 0;
  }

  /**
   * Checks if the address is a temporary unsaved
   * address.
   *
   * The address is new if it has a negative ID.
   *
   * @access public
   * @return boolean
   *   TRUE if the address is new.
   *   FALSE if the address is saved in the database.
   */
  public function isNew() {
    return $this
      ->getId() < 1;
  }

  /**
   * Returns address name if given.
   *
   * If the address has no name, it will use the
   * address format as label instead.
   *
   * @return string
   *   The address name.
   * @todo better alternative for address name?
   */
  public function label() {
    $name = $this
      ->getName();
    if ($name) {
      return $name;
    }
    return preg_replace('/<.*?>/', ', ', trim(uc_addresses_format_address($this)));
  }

  /**
   * Returns the uri of the address.
   *
   * @return array
   *   The addres uri.
   */
  public function uri() {
    return array(
      'path' => 'user/' . $this
        ->getUserId() . '/addresses/' . $this
        ->getId(),
    );
  }

  // -----------------------------------------------------------------------------
  // uc_addresses features
  // -----------------------------------------------------------------------------

  /**
   * Override of UcAddressesSchemaAddress::getField().
   *
   * Getting some of the schema fields differently.
   *
   * @param string $fieldName
   *	 The name of the field whose value we want.
   *
   * @access public
   * @return mixed
   *	 The field value.
   * @throws UcAddressInvalidFieldException
   */
  public function getField($fieldName) {
    switch ($fieldName) {
      case 'aid':
        return $this
          ->getId();
      case 'uid':
        return $this
          ->getUserId();
    }
    return parent::getField($fieldName);
  }

  /**
   * Override of UcAddressesSchemaAddress::setField().
   *
   * Prevents setting some schema fields directly.
   *
   * @param string $fieldName
   *   The name of the field whose value we will set.
   * @param mixed $value
   *   The value to which to set the field.
   *
   * @access public
   * @return void
   * @throws UcAddressInvalidFieldException
   */
  public function setField($fieldName, $value) {
    switch ($fieldName) {
      case 'aid':

        // Don't set.
        // @todo Throw an Exception here?
        break;
      case 'uid':

        // Only set if the address is unowned. Else, ignore it.
        // @todo Throw an Exception here?
        if (!$this
          ->isOwned()) {
          $this
            ->setOwner($value);
        }
        break;
      case 'address_name':
        $this
          ->setName($value);
        break;
      case 'default_shipping':
        if ($value) {
          $this
            ->setAsDefault('shipping');
        }
        break;
      case 'default_billing':
        if ($value) {
          $this
            ->setAsDefault('billing');
        }
        break;
      default:
        parent::setField($fieldName, $value);
        break;
    }
  }

  /**
   * Returns the nickname of the address.
   *
   * @access public
   * @return string
   *   The name of this address.
   */
  public function getName() {
    return $this
      ->getSchemaAddress()->address_name;
  }

  /**
   * Sets the nickname of the address.
   *
   * @param string $name
   *   The name to give to the address.
   *
   * @access public
   * @return boolean
   *   TRUE if setting name was succesful.
   *   FALSE otherwise.
   */
  public function setName($name) {
    if ($this
      ->getName() === $name) {

      // Address already has this name, do nothing
      return TRUE;
    }
    if ($this->addressBook
      ->setAddressName($this, $name)) {
      $this
        ->setDirty();
      return TRUE;
    }
    return FALSE;
  }

  /**
   * Tells if the address is a default address of type $type.
   *
   * @param string $type
   *   The type of default.
   *
   * @access public
   * @return boolean
   *   TRUE if the address is a default address of type $type.
   *   FALSE otherwise.
   */
  public function isDefault($type = 'billing') {
    return $this
      ->getSchemaAddress()->{'default_' . $type};
  }

  /**
   * Sets this address as a default address of type $type
   *
   * @param string $type
   *   The type of default to set (e.g., delivery, billing).
   *
   * @access public
   * @return void
   */
  public function setAsDefault($type = 'billing') {
    if ($this
      ->isDefault($type)) {

      // Is already default $type, do nothing so the address doesn't
      // get unnecessary "dirty".
      return;
    }
    $this->addressBook
      ->setAddressAsDefault($this, $type);
    $this
      ->setDirty();
  }

  /**
   * Changes the owner of this address.
   *
   * @param int $uid
   *   The new owner of the address.
   *
   * @access public
   * @return UcAddressesAddressBook
   *   The address book the address will belong to;
   *   or NULL if the address was already owned.
   */
  public function setOwner($uid) {

    // The owner of this address may only be changed if it doesn't belong to
    // anyone yet.
    if ($this
      ->isOwned()) {

      // Changing the owner not allowed.
      return;
    }

    // Setting the owner goes via the address book.
    return $this->addressBook
      ->setAddressOwner($this, $uid);
  }

  /**
   * Deletes address from address book.
   *
   * @access public
   * @return boolean
   *   TRUE if the address was deleted.
   *   FALSE otherwise.
   */
  public function delete() {
    return $this->addressBook
      ->deleteAddress($this);
  }

  // -----------------------------------------------------------------------------
  // SAVING
  // -----------------------------------------------------------------------------

  /**
   * Saves address if address is marked as 'dirty'.
   *
   * @access public
   * @return void
   * @throws UcAddressesDbException
   * @throws UcAddressesUnownedException
   */
  public function save() {
    if (!$this
      ->isOwned()) {
      throw new UcAddressesUnownedException(t('The address can not be saved because it is not owned by an user.'));
    }
    if ($this
      ->isDirty()) {

      // Allow other modules to alter the address before saving.
      module_invoke_all('uc_addresses_address_presave', $this);
      $address = $this
        ->getSchemaAddress();
      $address->modified = time();
      $address->uid = $this
        ->getUserId();
      if ($address->aid < 0) {
        unset($address->aid);
        $address->created = time();
        $result = drupal_write_record('uc_addresses', $address);
        $hook = 'insert';

        // Tell address book the address now has a definitive ID.
        $this->addressBook
          ->updateAddress($this);
      }
      else {
        $result = drupal_write_record('uc_addresses', $address, array(
          'aid',
        ));
        $hook = 'update';
      }
      if ($result === FALSE) {
        throw new UcAddressesDbException(t('Failed to write address with id = %aid', array(
          '%aid' => $address->aid,
        )));
      }

      // Address is saved and no longer 'dirty'.
      $this
        ->clearDirty();

      // If this a default address, ensure no other addresses are marked as
      // default in the database.
      if (function_exists('uc_addresses_address_types')) {

        // During installation the function 'uc_addresses_address_types()'
        // may not be available yet.
        $default_types = uc_addresses_address_types();
      }
      else {
        $default_types = array(
          'shipping',
          'billing',
        );
      }
      foreach ($default_types as $default_type) {
        if ($this
          ->isDefault($default_type)) {

          // Mark all addresses of the address owner as non-default except
          // the current address.
          db_query("UPDATE {uc_addresses} SET default_%s = 0 WHERE uid = %d AND aid != %d", $default_type, $address->uid, $address->aid);
        }
      }

      // Notify other modules that an address has been saved.
      module_invoke_all('uc_addresses_address_' . $hook, $this);
    }
  }

  // -----------------------------------------------------------------------------
  // REPRESENTATION
  // -----------------------------------------------------------------------------

  /**
   * Returns address html.
   *
   * @access public
   * @return string
   *   The themed address, as HTML.
   * @todo Should maybe return "address display" instead.
   */
  public function __toString() {
    return theme('uc_addresses_list_address', $this);
  }

  /**
   * Export address instance to PHP code.
   *
   * @return string
   *   PHP-code to reconstruct the address with.
   */
  public function varExport() {
    $data = $this
      ->getRawFieldData();
    $code = '$fields = ' . var_export($data, TRUE) . ";\n";
    $uid = $this
      ->getUserId();
    if ($uid) {
      $code .= '$address = UcAddressesAddressBook::get(' . $uid . ')->addAddress();' . "\n";
    }
    else {
      $code .= '$address = UcAddressesAddressBook::newAddress();' . "\n";
    }
    $code .= '$address->setMultipleFields($fields);' . "\n";
    return $code;
  }

  // -----------------------------------------------------------------------------
  // Low-level calls intended only for UcAddressesAddressBook
  // -----------------------------------------------------------------------------

  /**
   * Sets a private variable.
   *
   * This method should only be called by the address book.
   *
   * @param string $fieldName
   *   The field to set a value for.
   * @param string $value
   *   The value to set.
   *
   * @access public
   * @return void
   */
  public function privSetUcAddressField($fieldName, $value) {
    switch ($fieldName) {
      case 'name':
      case 'address_name':
        $this
          ->getSchemaAddress()->address_name = $value;
        break;
      case 'shipping':
      case 'default_shipping':
        $this
          ->getSchemaAddress()->default_shipping = $value ? TRUE : FALSE;
        break;
      case 'billing':
      case 'default_billing':
        $this
          ->getSchemaAddress()->default_billing = $value ? TRUE : FALSE;
        break;
    }
    $this
      ->setDirty();
  }

  /**
   * Modify the address book of this address.
   *
   * This can only be done if the address book already accepted
   * the address as one of it's addresses.
   *
   * @param UcAddressesAddressBook $addressBook
   *   The address book to move this address to.
   *
   * @access public
   * @return boolean
   *   TRUE on success.
   *   FALSE otherwise.
   */
  public function privChangeAddressBook(UcAddressesAddressBook $addressBook) {
    foreach ($addressBook
      ->getAddresses() as $address) {
      if ($address === $this) {

        // Address appears in address book, changing address book approved.
        $this->addressBook = $addressBook;
        return TRUE;
      }
    }
    return FALSE;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
UcAddressesAddress::$addressBook private property The address book the address belongs to.
UcAddressesAddress::$nextNewAid private static property Which ID a new address will get when constructed.
UcAddressesAddress::copyAddress public function Make a copy of this address.
UcAddressesAddress::delete public function Deletes address from address book.
UcAddressesAddress::getAddressBook public function Returns the address book the address is in.
UcAddressesAddress::getField public function Override of UcAddressesSchemaAddress::getField(). Overrides UcAddressesSchemaAddress::getField
UcAddressesAddress::getId public function Returns address ID.
UcAddressesAddress::getName public function Returns the nickname of the address.
UcAddressesAddress::getUserId public function Returns owner of this address.
UcAddressesAddress::identifier public function Alias of getId().
UcAddressesAddress::isDefault public function Tells if the address is a default address of type $type.
UcAddressesAddress::isNew public function Checks if the address is a temporary unsaved address.
UcAddressesAddress::isOwned public function Checks if the address is owned by an user.
UcAddressesAddress::label public function Returns address name if given.
UcAddressesAddress::newAddress public static function Create a new unowned address.
UcAddressesAddress::privChangeAddressBook public function Modify the address book of this address.
UcAddressesAddress::privSetUcAddressField public function Sets a private variable.
UcAddressesAddress::save public function Saves address if address is marked as 'dirty'.
UcAddressesAddress::setAsDefault public function Sets this address as a default address of type $type
UcAddressesAddress::setField public function Override of UcAddressesSchemaAddress::setField(). Overrides UcAddressesSchemaAddress::setField
UcAddressesAddress::setName public function Sets the nickname of the address.
UcAddressesAddress::setOwner public function Changes the owner of this address.
UcAddressesAddress::uri public function Returns the uri of the address.
UcAddressesAddress::varExport public function Export address instance to PHP code.
UcAddressesAddress::__construct public function UcAddressesAddress object constructor. Overrides UcAddressesSchemaAddress::__construct
UcAddressesAddress::__sleep public function Tells which members may kept when the address is being serialized. Overrides UcAddressesSchemaAddress::__sleep
UcAddressesAddress::__toString public function Returns address html.
UcAddressesAddress::__wakeup public function Restore variables when the address is unserialized. Overrides UcAddressesSchemaAddress::__wakeup
UcAddressesSchemaAddress::$dirty private property TRUE if the address is changed after being loaded or created.
UcAddressesSchemaAddress::$schemaAddress private property The base schema address object.
UcAddressesSchemaAddress::$sleep protected property A variable that's used to keep data when the address object. is being serialized.
UcAddressesSchemaAddress::clearDirty protected function Clear the dirty flag.
UcAddressesSchemaAddress::compareAddress public function Checks if the schema address of the given address is equal to the schema address of this.
UcAddressesSchemaAddress::fieldExists public static function Returns TRUE if field is registered through the API.
UcAddressesSchemaAddress::fieldMustExist private static function Throws an exception if the field does not exist.
UcAddressesSchemaAddress::getDefinedFields public static function Returns defined fields.
UcAddressesSchemaAddress::getFieldData public function Returns "safe" field data.
UcAddressesSchemaAddress::getFieldValue public function Get a "safe" field value from a single field.
UcAddressesSchemaAddress::getHandler public function Returns a handler instance.
UcAddressesSchemaAddress::getRawFieldData public function Returns "raw" field data (contents of the schema address object).
UcAddressesSchemaAddress::getSchemaAddress protected function Get the aggregated schema address.
UcAddressesSchemaAddress::isDirty protected function Reports if the address is modified since it was loaded from the database.
UcAddressesSchemaAddress::schemaFieldExists public static function Returns TRUE if field is part of the schema.
UcAddressesSchemaAddress::schemaFieldMustExist private static function Throws an exception if the schema field does not exist.
UcAddressesSchemaAddress::setDirty protected function Set the dirty flag.
UcAddressesSchemaAddress::setMultipleFields public function Set multiple fields at once.
UcAddressesSchemaAddress::setSchemaAddress protected function Set the aggregated schema address.
UcAddressesSchemaAddress::__get public function Magic getter.
UcAddressesSchemaAddress::__isset public function Magic method for giving back if property exists or not.
UcAddressesSchemaAddress::__set public function Magic setter.