The address book API: The address book class

Last updated on
9 May 2017

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

The goal of the address book class is to hold a list of addresses that are currently loaded or added during the request. It is designed so that when the address book is asked for the same address twice during one request, it doesn't need to look it up in the database again.
Each instance of the address book class belongs to one user and each user can only have one address book.

Table of contents

Create an address book instance for user $uid

The address book class follows the singleton design pattern. The class itself controls when instances of UcAddressesAddressBook are created. When you want to create or get an address book instance for user $uid, you will have to call the static method get().

<?php
// Get the address book instance for user $uid
$addressBook = UcAddressesAddressBook::get($uid);
?>

When above code is called, the address book checks if there is already an address book instance for user $uid. Address book instances are saved in the static private variable $singleton. If an instance is found, the address book class will return it. If there is not, the address book class will create a new address book instance and assign it to the user the address book was requested for.

Retrieve a single address for one user

The address book delivers several methods for getting a single address. You can get an address:

  • by it's ID: getAddressById($aid);
  • by it's name: getAddressByName($name);
  • by it's "default" type ("shipping" or "billing"): getDefaultAddress($type).

For the above three methods you need to first get the address book instance for the user you want to get an address for. Here is an example for getting an address with ID 2 from user 1:

<?php
// Load address with ID 2 from user 1
$address = UcAddressesAddressBook::get(1)->getAddressById(2);
?>

If the address is found you will get an instance of UcAddressesAddress. If the address is not found, FALSE will be returned.

The address book class contains also a static method to get an address in case you know the address ID, but not the user ID. This method is called loadAddress(). This method is slower than the getAddressById() method, because it first needs to go through all address book instances to see if one of them contains an address with that ID. So you are encouraged to use it only when you don't know the user ID.

<?php
// Get an address when the user ID is unknown
$address = UcAddressesAddressBook::loadAddress($aid);
?>

There is no equivalent for getting an address by name when the user ID is not known. This is because address names are only unique per user and not unique in general.

Retrieve all addresses for one user

To get all addresses for one user, you can call the method getAddresses().

<?php
// Get all addresses for user $uid
$addresses = UcAddressesAddressBook::get($uid)->getAddresses();
?>

Adding addresses

To add a new address for an user, call the method addAddress(). This will return a new UcAddressesAddress instance. Because this address does not yet exists in the database, it will have a negative ID. However, it is tracked by the address book, so you are able to get it from the address book by calling getAddressById(). Once you save the address, the address will get a definitive ID assigned.

<?php
// Create a new address for user $uid
$address = UcAddressesAddressBook::get($uid)->addAddress();
?>

Saving

You can save all the addresses in the address book at once by calling the method save(). Only addresses that are marked as "dirty" (changed) will actually be written to the database. The presave, insert, and update hooks are only invoked for changed addresses.

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

Deleting an address

The address book class has three methods for deleting a single address:

  • deleteAddress($address)
  • deleteAddressById($aid)
  • deleteAddressByName($name)

The first method needs an UcAddressesAddress object to delete the address and it will only delete it if the address actually belongs to that address book. The second method needs an address ID and the third the address name. The last two methods will first load the address from the database if it's not yet available in the address book.
Calling any of these methods will delete an address from both the database (if it was saved) and the address book.

The easiest way to delete a single address is just to call the method delete() on the address object:

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

The address object will then call deleteAddress() from the address book it belongs to itself. After deletion, you can still use the address object, but it's gone from the database and it's no longer tracked by the address book.

The address book has no method for deleting all addresses at once.

Performance Hinting

Before you ask the address book instance for addresses, you can tell how you plan to use the address book: if you plan to just request one address or plan to request multiple addresses. If you plan to request more than one address it's better for performance to let the address book load all addresses for one user from the database at once then that it needs to load every single address separately. For this the address book has an performance hint setting, which you can set to:

  • PERF_HINT_LOAD_ONE (default, used when is planned to request a single address)
  • PERF_HINT_LOAD_ALL (used when planned to request multiple addresses)

You can set the performance hint by calling setPerformanceHint(). To retrieve the performance hint setting, call getPerformanceHint(). Example:

<?php
// Tell the address book we want to get multiple addresses
$addressBook->setPerformanceHint(UcAddressesAddressBook::PERF_HINT_LOAD_ALL);
?>

If you just want to get all addresses at once, you don't have to set the performance hint. You can call the method getAddresses() for that.

Help improve this page

Page status: No known problems

You can: