Documentation

Prerequisites / Dependencies

PHP iAddressbook does only have very little dependencies since I wanted it to work on as many systems as possible.

You will need:

  • PHP (Version 4.3 or higher)
  • a database (MySQL or SQLite, ADOdb is used as abstraction layer)
  • (optional) iconv (if you want to import vcards that are not UTF-8 encoded)
  • (optional) ImageMagick's convert or GD (if you want to import photos)

Installation

Installing the address book consists of four steps:

  1. Copy all files to your web space
  2. Open your web browser and point it to your installation. You will be automatically redirected to the first time installation
  3. Follow the steps in the installer
  4. If you want authorization support enable it during the installation. You need to manually create users in conf/auth.php for now. You will find instructions in conf/auth.php.

Upgrade

The easiest way to upgrade is to use the vCard export feature to get all your contacts and then import these contacts into a new installation. You won't lose any data as the vCard export preserves all fields!

Follow these steps and you should be on the safe side:

  1. Export all your contacts using the vCard export.
  2. Install the addressbook as described in the installation chapter.
  3. Import your vCard into the new addressbook. Use the folder import feature if you

have a lot of contacts.

  1. If everything works as expected, remove the old installation and rename/move your

new installation to the old place.

The changelog can be found here

Import

Import should work out of the box as the addressbook can auto-detect the most important encodings. The addressbook can detect vCards in the following encodings:

  • UTF-8
  • UTF-16
  • UTF-32
  • (ISO-8859-1)

All UNICODE encodings are auto-detected even if the file does not have a Byte Order Mark (BOM). The last encoding (here: ISO-8859-1) is a fallback encoding if auto-detection does not work (or if the file is not UTF encoded) and can be configured in the configuration file. All encodings supported by iconv are available.

Conversion

You can use a tool like iconv to change the encoding of your vCards. This is usually not needed. Only try it if the address book does not correctly auto-detect your vCards. Please file a bug report in that case.

In Mac OS X you can to so by opening a console window and typing:

iconv -f UTF-16BE -t UTF-8 vcard.vcf > converted_vcard.vcf

or

iconv -f UTF-16 -t UTF-8 vcard.vcf > converted_vcard.vcf

Permissions / Access Controls

Since version 0.98 the iAddressBook has advanced authentication support. Every logged in user has a set of actions which he is allowed to execute. That way we have complete control over who is allowed to add contacts and who may delete groups or export vCards. If the user is not logged in he can be optionally mapped to a guest account. The guest permissions can be configured as well. Let's see how it works.

Activate Authentication

  • First of all we have to activate authentication support (as long as this is disabled, everyone has full access to the iAddressBook). You can do this in conf/config.php.
  $conf['auth_enabled'] = 1;
  • If we want to allow Guest Access we can enable it in conf/config.php.
  $conf['auth_allow_guest'] = 1;

Creating User Accounts

  • Now we have to setup user accounts. As with prior versions they are all managed inside /conf/auth.php. Let's create a user with username=fred, password=banana and permissions to execute the actions 'show' and 'img'. Fred should also be member of the group '@editors'. The ACL entry looks like this:
  $auth['fred']['password']    = '72b302bf297a228a75730123efef7c41';
  $auth['fred']['permissions'] = array( 'img', 'show' );
  $auth['fred']['groups']      = array('@editor');
  $auth['fred']['fullname']    = 'Fred The Geek';
  $auth['fred']['email']       = 'fred@geeks.org';
  • PASSWORD: The password value contains the MD5-encrypted password (here: banana). You can calculate the MD5 sum in the login form of the iAddressBook by entering 'make md5' into the username field and your password into the password field.
  • PERMISSIONS: This field contains an array of actions which this user is allowed to execute
  • GROUPS: This field contains an array of groups this user is a member of. The user will inherit all allowed actions from the group
  • FULLNAME: This field is only for convenience and contains the full name of the user
  • EMAIL: This field is only for convenience and contains the e-mail address of the user
  • As the address book already comes with pre-defined groups (@admin, @editor, @guest) you will probably not need the 'permissions' field.

Creating Groups

  • Groups are also maintained within /conf/auth.php and /lib/default/auth.php. The syntax is basically the same as with user accounts. Groups only need the permissions field. It should be pretty self explanatory.
$auth['@admin']['permissions']  = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many', 'select_letter', 'select_offset',
                                        'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',
                                        'import_vcard', 'import_folder', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat', 
                                        'login', 'logout', 'reset',
                                        'debug', 'check', 'info');
 
 
$auth['@editor']['permissions'] = array('show', 'img', 'search', 'edit', 'new', 'save', 'delete', 'delete_many', 'select_letter', 'select_offset',
                                        'cat_select', 'cat_add', 'cat_del', 'cat_del_empty', 'cat_add_contacts', 'cat_del_contacts',
                                        'import_vcard', 'import_folder', 'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat',
                                        'login', 'logout', 'reset');
 
 
$auth['@guest']['permissions']  = array('show', 'img', 'search', 'select_letter', 'select_offset',
                                        'cat_select', 
                                        'export_vcard', 'export_vcard_cat', 'export_csv_cat', 'export_ldif_cat',
                                        'login', 'logout', 'reset');
 
$auth['@xml_client']['permissions']  = array('xml_version',
                                        'xml_search', 'xml_search_email', 'xml_get_contact', 'xml_get_contacts', 'xml_count_contacts',
                                        'xml_set_contact', 'xml_delete_contact',
                                        'xml_import_vcard', 'xml_export_vcard');

Guest Account

  • The guest account is a normal user account an can also be configured like any other user account. The guest username is 'guest'. The default permissmions allow viewing, exporting and searching but do not allow changes to the iAddressBook.
  • Do not add a password to the guest account.
$auth['guest']['permissions']   = array('show', 'img', 'search', 
                                        'cat_select', 
                                        'export_vcard', 'export_vcard_cat',
                                        'login', 'logout');
$auth['guest']['groups']        = array();
$auth['guest']['fullname']      = 'Guest';
$auth['guest']['email']         = '';

Actions Index

The default action is 'show'. Whenever a user requests an action which he has no permission to execute the address book will execute 'show' instead.

ActionDescription
show Displays the address book with all contacts and detail view (this is the default action).
img Displays the users image
search Search for contacts
edit Display the edit form for an existing contact
new Display the edit form for a new contact
save Save a contact (which was previously created with 'new' or edited with 'edit'
delete Delete a contact (using the button in the contact detail page)
delete_many Delete selected contacts (using the link from the contact list)
select_letter Filters contact view by letter
select_offset Filters contact view by offset (used when not all contacts are shown)
cat_select Select a category
cat_add Create a category
cat_del Delete a category
cat_del_empty Delete all empty categories
cat_add_contacts Add contacts to a category
cat_del_contacts Remove contacts from a category
import_vcard Import a vCard
import_folder Import all vCards (*.vcf) that can be found in the _import folder
export_vcard Export a vCard
export_vcard_cat Export selected contacts as vCard (from the contactlist)
export_csv_cat Export selected contacts as CSV file
export_ldif_cat Export selected contacts as LDIF file
login Display the login screen
logout Logout
debug Display debugging information
check Check if the installation of iAddressBook works properly (database, file system access, etc.)

XML-RPC API

CardDAV Interface

Contact Format

  • title
  • firstname
  • second firstname
  • lastname
  • suffix
  • phonetic firstname, lastname
  • nickname
  • jobtitle
  • department
  • organization
  • photo
  • birthdate
  • notes
  • categories
  • unlimited addresses
  • unlimited phones
  • unlimited emails
  • unlimited urls
  • unlimited chat handles (AIM, ICQ, MSN, Jabber, Yahoo)
  • unlimited related names
  • creation date
  • modification date
  • UID

Unsupported fields

  • maidenname (X-MAIDENNAME)
  • custom dates (X-ABDATE)
  • addressbook UID (X-ABUID)

These fields will not be included since I have absolutely no need for them. The current design is transparent enough for me.

QR Code
QR Code docs (generated for current page)