Contact management

Database

Webasyst stores contact-related data in several database tables.

wa_contact: basic contact details
id: contact ID (auto_increment)
name: full contact name generated when contact details are saved
firstname: name
middlename: second name
lastname: last name
title: salutation (e.g., Mr. or Mrs.)
company: company name
is_user: designates whether the contact is a backend user, default value is 0
login: backend user's login name
password: password to access the backend
birthday: date of birth (DATE)
about: arbitrary text description (TEXT)
photo: filename of the contact's photo
locale: contact's locale designating the language in which web interfaces should be displayed to this contact; e.g., en_US or ru_RU
timezone: contact's time zone; e.g., Europe/Dublin

System values are stored in the same table:
create_datetime: contact creation date and time
create_app_id: APP_ID of the application, which has created the contact
create_method: contact creation method (e.g., add - manual adding, import, form - via a subscription form, etc.),
create_contact_id: ID of another contact, who has manually created the current contact

wa_contact_emails is the table for storing contacts' additional email addresses
id: unique email address ID (auto_increment)
contact_id: contact ID
email: email address
ext: extra information such as home - personal/home address, work - work address, etc.
sort: the email addresses displaying order; the address with the sort value equal to 0 is considered contact's main email address (which is used for sending email messages to the contact, for authorization, etc.), all other addresses are considered as auxiliary
status: enum('unknown', 'confirmed', 'unconfirmed', 'unavailable'); designates the current email address status: unknown (e.g., added manually), confirmed, non-confirmed, unavailable (e.g., if an email message has been returned at an attempt to send to send it to this address)

wa_contact_data is the table for storing extra custom data данных (phone number, postal address, etc.)
id: uniquer record ID
contact_id: contact ID
field: string-type file identifier; e.g., phone, url
ext: extra information (home, work, etc.)
value: field value; VARCHAR(255)
sort: field display order

The same table also contains composite fields, i.e. those containing several subfields. For example, address (subfield names are specified after the column sign):
address:country
address:city
address:state
address:street
address:zip

Contact fields descriptions

All fields, which can be saved for a contact, are descripbed in file wa-system/contact/data/field.php. For example, here is how the description of the "phone" field looks (below is shown a portion of file field.php):

new waContactPhoneField('phone', 'Phone', array(
    'multi' => true, // each contact may have several phone numbers
	'ext'   => array( // a set of available descriptive "extensions"
		'work'   => 'Work',
		'mobile' => 'Mobile',
		'home'   => 'Home',
	)
)),

In order to add a new field for contacts, you need to do the following:

1. Add its description to file wa-config/apps/contacts/custom_fields.php. For example, field "car":

   <?php
   
   return array(
       new waContactStringField(
           'car',
           array(
               'en_US' => 'Car',
               'de_DE' => 'Auto',
               array()
           )
       ),
   );
   

2. Enable the new field by adding the following string to the end of file wa-config/apps/contacts/person_fields_order.php

   'car' => array()

   If there is no such file, create it and copy the entire contents of file wa-system/contact/data/person_fields_default.php) into it.

   <?php
   
   return array(
        //... here are all other fields
        'car' => array()
   );
   

Contact creation and editing

All necessary contact management methods are provided by class waContact. It is strongly discouraged to modify or read contact data directly from the database. It is very easy to use class waContact:

// creating a new contact instance

// new contact
$contact = new waContact();
// existing conitact
$contact = new waContact($id);

// modifying contact data
$contact[$field] = $value;

//specifying the email address
$contact['email'] = 'test@domain.com';
//alternative method
$contact['email'] = array(
    'value'  => 'test@webasyst.com', 
    'ext'    => 'work',
    'status' => 'confirmed'
);

Several email addresses can be specified in a similar fashion:

$contact['email'] = array(
    'email1@domain.com',
    'email2@domain.com'
);

Please keep in mind that the above examples will delete all email address previously stored in an existing conitact. To add a new address to a contact, use method add:

$contact->add('email', 'newemail@domain.com');

In order to save all changes to the database, call method save():

$contact->save();

The method returns 0 upon successful completion or an error array otherwise:

if ($errors = $contact->save()) {
	//array of errors occurred during the contact saving
}

You can also pass an array of data to be saved to method save() as a parameter. Example:

$contact->save(array(
    'phone' => array(
        'value' => '4354235',
        'ext'  => 'work'
    ),
    'email'  => 'test@domain.com'
));

Deleting a value

unset($contact['email']); 
$contact->save();
// all contact's email addresses have been deleted

Retrieving contact's data

$contact = new waContact($id);

$emails = $contact['email'];
$emails = $contact->get('email');

Because a contact can have several email addresses, then the $emails variable will contain an array of retrieved values in the form shown in the example below:

array(
    0 => array (
           [value]  => email1@domain.com,
           [ext]    => home,
           [status] => unknown
    ),
    1 => array (
           [value]  => email2@domain.com,
           [ext]    => work,
           [status] => confirmed
    ),
);

This refers to all fields, which can have several values.

In the situations, when you need to get only one field value (e.g., the main email address to send a message to the contact), consider using the following approach:

$email = $contact->get('email', 'default'); // get the contact's first email address

Contact name:

$name = $contact['name'];

$name = $contact->getName();

$id = $contact['id']; 

$id = $contact->getId();

Composite fields

Composite fields are the fields containing of several subfields. For example, a postal address consists of the ZIP number, the country & state name, the city, and the street address.

$contact->get('address');

Array
(
    [0] => Array
        (
            [data] => Array
                (
                    [city]    => Newark
                    [country] => usa
                    [street]  => 665 Dawson Drive
                )

            [ext]   => work
            [value] => 665 Dawson Drive, Newark, United States of America
        )

)

The value item of the resulting array contains the value prepared for displaying (the pre-processing logic is executed by the class describing the field type). The data item contains an array of all subfields' values.

Be careful when editing such fields. For example, the city name in the first address of the contact should be edited as shown below:

$address = $contact->get('address');
$address[0]['data']['city'] = 'Newark';
$contact->save(array('address' => $address));

Adding another address:

$contact->add(
    'address',
    array(
        'city'    => 'Moscow',
        'country' => 'rus'
    )
);
$contact->save();

The current user's object (wa()->getUser(), or $this->getUser() when used within actions or controller classes) is also an instance of the waContact class. Therefore, all the above information is also applicable for this user class.

Examples:

//get current user's name
$this->getUser()->getName();
  
//get main email address
$this->getUser()->get('email', 'default');