The address book API: The address classes

Each address instance used by Ubercart Addresses is of type UcAddressesAddress. This class holds address information, such as first name, last name, country, etc. Each instance is created through the address book, so the address book is able to keep track of all the addresses it contains. The UcAddressesAddress class extends UcAddressesSchemaAddress.

Table of contents

• Differences between UcAddressesAddress and UcAddressesSchemaAddress
• Create an address instance
• Saving an address
• Delete an address
• Setting and getting address fields
• Change the nickname of an address
• Set an address as the default shipping or the default billing address
• Getting the addresses' address book
• Temporary and definitive address ID's
• Ownership of addresses
• Compare addresses
• Copying addresses

Differences between UcAddressesAddress and UcAddressesSchemaAddress

• UcAddressesSchemaAddress is for address fields, UcAddressesAddress is for address book features
  The UcAddressesSchemaAddress class deals with setting and getting address fields and it's connected with the field handler API (provided by Ubercart Addresses), while the UcAddressesAddress implements specific address book features such as having unique nicknames and the concept of default shipping and default billing addresses.
• UcAddressesAddress is connected with UcAddressesAddressBook
  The UcAddressesAddress class works together with the UcAddressesAddressBook class and for many operations it needs to interact with that class. For example, when you want to change the nickname of an address, the UcAddressesAddress class asks the UcAddressesAddressBook class for finding any name collisions. The UcAddressesSchemaAddress does not interact with the address book class and works without it.
• UcAddressesSchemaAddress doesn't interact with the database, while UcAddressesAddress does
  The UcAddressesSchemaAddress does not interact with the database, which means with this class alone you can't save addresses to the database (unless you implement this with outside code). The UcAddressesAddress class contains a method to save an address and a method to delete an address. Loading addresses can only be done via the UcAddressesAddressBook class.

Create an address instance

When you want to work with an address instance, always create this with the address book class. The address book keeps track of addresses currently loaded or created.
With the following methods in the address book class you can create a new "empty" address:

• addAddress()
  Creates a new address which is (temporary) added to the address book of a specific user. Remains temporary until it's saved.
• newAddress()
  Adds a new unowned address (which can not be saved to the database).

Read more about how to work with the address book class first if you not already have done so.

Saving an address

To save a single address, simply call the method save(). If you want to save multiple addresses it's better to call the save() method of the address book. This is mandatory when you mark the address as the default shipping or default billing address as that will result in changes in multiple addresses.
Saving of an address only happens if the address is "dirty", which means if the address was changed since it was loaded from the database. New created addresses are always marked "dirty".
Before saving, the hook hook_uc_addresses_address_presave() is invoked. After saving, the hook hook_uc_addresses_address_insert() is invoked in case the address was new or the hook hook_uc_addresses_address_update() is invoked in case the address already existed in the database.

<?php
// Save a single address
$address->save();
// Save all addresses in the address book
$addressBook->save();
?>

Delete an address

To delete an address, call delete(). This will delete the address from the database (if it was saved) and from the address book it is in. Default addresses can not be deleted.

<?php
// Delete a address
$address->delete();
?>

Setting and getting address fields

You can set an address field by calling the method setField(). Only known fields can be set. If you want to set a custom field this way, you have to declare this field first with hook_uc_addresses_fields(). To temporary save data, just set it like you normally would do with other objects: <?php $address->mydata = 'value'; ?>
To get a fields value, call getField(). You will receive the "raw" unsanitized value.
For receiving all address field values at once, you can call getFieldData() to receive the field values that are safe for output. To receive the "raw" address field values, you can call getRawFieldData().

<?php
// Set a field value
$address->setField('first_name', 'Chris');

// Get a field value
$first_name = $address->getField('first_name');

// Get all field values for output
$values = $address->getFieldData();

// Get all "raw" field values
$values = $address->getRawFieldData();
?>

Change the nickname of an address

Nicknames are unique per address book. You can set an address nickname by calling setName(). This method will ask the address book if an other address already has this name. If this is the case, the name of the address will not be changed and FALSE will be returned. If setting the address name succeeded, TRUE will be returned. Empty nicknames may be used multiple times for addresses, so it's not required that every address must have a nickname.
To get the address nickname, call getName().

<?php
// Set the nickname of the address
$address->setName('myname');

// If the nickname is already used for an other address, FALSE will be returned.
$address1->setName('myname');
$address2->setName('myname'); // Will result into FALSE, because $address1 has 
                              // already that name. The address name will be unchanged.

// Get the nickname of the address
$name = $address->getName();
?>

Set an address as the default shipping or the default billing address

Addresses can be marked as default shipping, default billing or both. Each address book can only have one default shipping address and only one default billing address. This may be the same address. To mark an address as the default, call setAsDefault(). The address book will then change the previous address that was marked as the default. When you want to save the address after changing the "default" setting, make sure to save all addresses in the address book or else you wind up with a corrupted database table as then multiple addresses are marked as the same default type.
To find out if an address is the default shipping or the default billing, call isDefault().

<?php
// Set this address as the default shipping address.
$address->setAsDefault('shipping');

// Set this address as the default billing address.
$address->setAsDefault('billing');

// Check if this address is the default shipping address.
if ($address->isDefault('shipping')) {
  // (Perform actions...)
}

// Check if this address is the default billing address.
if ($address->isDefault('billing')) {
  // (Perform actions...)
}
?>

Getting the addresses' address book

An address instance knows to which address book it belongs. To get the instance of the address book the address belongs to, call getAddressBook().

<?php
// Retrieve address book of address
$addressBook = $address->getAddressBook();
?>

Temporary and definitive address ID's

When a new address is created (not saved in the database) it will get a temporary negative ID, so the address book is able to keep track of this address (the address book indexes addresses by it's ID). When you save the address it will get a definitive address ID. The temporary address ID will be gone and the address book will update it's addresses index.
You can get the current address ID by calling getId().

<?php
// Get the address ID
$aid = $address->getId();
?>

Ownership of addresses

Addresses can only be owned by verified users (not anonymous users). To check who owns the address, call getUserId(). To check if the address is owned, call isOwned(). If the address is not owned, you can use the method setOwner() to set the owner. You can only set the owner of an address once. When an address is owned, you can't change it's owner. Read Working with anonymous users for more information about this.

<?php
// Get the address owner.
$uid = $address->getUserId();
// Check if the address is owned.

if ($address->isOwned()) {
  // (Perform actions...)
}

// Set the owner of the address (only works when it's unowned).
$address->setOwner($uid);
?>

Compare addresses

You can check if two address objects are considered equal by calling compareAddress(). This will not check if the address objects are exactly equal: it will only check certain address fields for differences. For example, the address ID, the user ID and whether the address is a default shipping or default billing address will be ignored in the comparison. When you declare fields through hook_uc_addresses_fields() you can specify if the field may be used in address comparisons by setting the "compare" value. When TRUE, it will be used in comparisons (the default). When FALSE, the field will be skipped. Read about declaring fields for more information about the "compare" value.

<?php
// Check if the addresses are equal.
if ($address->compareAddress($address2)) {
  // Addresses are considered equal.
}
else {
  // Addresses differ.
}
?>

Copying addresses

A copy of an address object can be made by calling copyAddress(). This will not create an exact copy. It will construct a new UcAddressesAddress instance and copy only the address field values over. The address fields aid, uid, address_name, default_shipping and default_billing will be reset. Optionally you can specify to which address book you want to copy the address.

<?php
// Make a copy of the address to be used in the same address book.
$address->copyAddress();

// Copy address over to an other address book.
$address->copyAddress($addressBook);
?>