waContact

Contact management

Contents...

A contact is a record about a person or an organization in the system storage. To obtain access to contact's methods or properties, first create an instance of waContact class; e.g.:

$contact = new waContact($id);
$contact_name = $contact->getName();

Methods

  • add

    Adds an extra value to the specified contact property.

  • addToCategory

    Adds a contact to specified category.

  • delete

    Deletes a contact.

  • delSettings

    Deletes a contact's property relating to the specified app.

  • get

    Returns the value of a contact's property.

  • getCache

    Returns the value of a contact's property stored in cache, without accessing the database.

  • getFirst

    Returns the first value of a contact's multi-field.

  • getId

    Returns the numeric id of a contact.

  • getLocale

    Returns a contact's locale.

  • getName

    Returns the value of a contact's name property.

  • getPasswordHash

    Returns the password hash.

  • getPhoto

    Returns a contact's photo URL.

  • getPhotoUrl

    Returns the photo URL of the specified contact.

  • getRights

    Returns information about a contact's access rights configuration.

  • getSettings

    Returns the properties of a cointact relating to specified app.

  • getStatus

    Returns the status of a user.

  • getTime

    Returns current data and time relative to a contact's locale and time zone configuration.

  • getTimezone

    Returns a contact's time zone value.

  • isAdmin

    Returns information about whether a user has full (administrative) access rights to all installed apps or only one specified app.

  • load

    Returns full information about a contact, which is stored in cache.

  • save

    Saves a contact's data to the database.

  • set

    Sets a value for the specified contact property.

  • setPhoto

    Adds an image to an existing contact.

  • setRight

    Sets access rights for a user.

  • setSettings

    Saves properties of the specified contact to the database.

  • validate

    Validates values of contact properties.

public function add ($field, $value)

Adds an extra value to the specified contact property.

Parameters

  • $field

    Property name.

  • $value

    Property value.

Example

$contact = new waContact();
$contact->set('email', 'email1@domain.com');
$contact->add('email', 'email2@domain.com');

public function addToCategory ($category_id)

Adds a contact to specified category. Applicable only for existing contacts stored in the database.

Parameters

  • $category_id

    Integer category id (or a string category id, only for system categories) to which a contact must be added.

Example

$contact = new waContact(1);
$contact->addToCategory(12);
$contact->addToCategory('blog');

public function delete()

Deletes a contact from the database.

Example

$contact = new waContact(123);
$contact->delete();

public function delSettings ($app_id, $name)

Deletes a contact's property relating to the specified app.

Parameters

  • $app_id

    App id.

  • $name

    Contact property id (string).

Example

$contact = new waContact(1);
$contact->delSettings('blog', 'nickname');

public function get ($field_id, $format = null)

Returns the value of a contact's property.

Parameters

  • $field_id

    Contact property id

  • $format

    String specifying the format in which the required data must be returned. The acceptable values are listed below:

    • default: simple text value of a contact property; for multi-fields, the first of available values is returned
    • value: simple text value of a contact property; for multi-fields, an array of all available values is returned
    • html: the full value of a contact property formatted by means of HTML code for displaying in a web page
    • js: simple text value of a contact property; for multi-fields, an array of all available values is returned, which contains the following elements for each value:
      • value: the value of a contact property formatted by means of HTML code for displaying in a web page
      • data: simple text value of a multi-field property as a string or array
      In addition to these basic elements, each sub-array of the returned array may contain other elements specific to various contact properties.
    • if no format is specified: simple text value of a contact property; for multi-fields, an array of all available values is returned, which contains a value element with a property's simple text value as well as other elements specific to various contact properties

Example

$contact = new waContact(123);
$contact->get('name');

Result

John Doe

Example

$contact = new waContact(123);
$contact->get('email', 'value');

Result

Array
(
    [0] => email1@domain.com
    [1] => email2@domain.com
)

Example

$contact = new waContact(123);
$contact->get('url', 'js');

Result

Array
(
    [0] => Array
        (
            [value] => <a target="_blank" href="http://domain1.com">domain1.com</a><a target="_blank" href="http://domain1.com"><i class="icon16 new-window"></i></a>
            [ext] => work
            [data] => http://domain1.com
        )

    [1] => Array
        (
            [value] => <a target="_blank" href="http://domain2.com">domain2.com</a><a target="_blank" href="http://domain2.com"><i class="icon16 new-window"></i></a>
            [ext] => personal
            [data] => http://domain2.com
        )

)

public function getCache ($field_id = null, $old_value = false)

Returns the value of a contact's property stored in cache, without accessing the database.

Parameters

  • $field_id

    Contact property id. If not specified, information about all properties of a contact is returned.

  • $old_value

    Flag requiring to return only contact property values retrieved from the database and to ignore dynamically added ones. If not specified, false is used by default: return both values stored in the database and those added dynamically.

Example

//retrieve information about a acontact and save it in cache
$contact = new waContact(123);
//dynamically add new values for 'email' property, which already contains several values retrieved from the database
$contact->add('email', 'extra1@domain.com');
$contact->add('email', 'extra2@domain.com');
//get the values 'email' property, both from the database and those dynamically added and saved in cache
$contact->getCache('email');

Result

Array
(
    [0] => Array
        (
            [value] => email1@domain.com
            [ext] => work
            [status] => unknown
        )

    [1] => Array
        (
            [value] => email2@domain.com
            [ext] => personal
            [status] => unknown
        )

    [2] => Array
        (
            [value] => extra1@domain.com
            [ext] => 
            [status] => unknown
        )

    [3] => Array
        (
            [value] => extra2@domain.com
            [ext] => 
            [status] => unknown
        )

)

Example

$contact = new waContact(123);
$contact->add('email', 'extra1@domain.com');
$contact->add('email', 'extra2@domain.com');
//get only the values retrieved from the database
$contact->getCache('email', true);

Result

Array
(
    [0] => Array
        (
            [value] => email1@domain.com
            [ext] => work
            [status] => unknown
        )

    [1] => Array
        (
            [value] => email2@domain.com
            [ext] => personal
            [status] => unknown
        )
)

public function getFirst ($field_id)

Returns the first value of a contact's multi-field.

Parameters

  • $field_id

    Contact property id.

Example

$contact = new waContact(123);
$contact->getFirst('email');

Result

Array
(
    [value] => email1@domain.com
    [ext] => 
    [status] => unknown
)

public function getId()

Returns the numeric id of a contact.

Example

$contact = new waContact(123);
$contact->getId();

Result

123

public function getLocale()

Returns a contact's locale.

Example

$contact = new waContact(123);
$contact->getLocale();

Result

en_US

public function getName()

Returns the value of a contact's name property.

Example

$contact = new waContact(123);
$contact->getName();

Result

John Doe

public static function getPasswordHash ($password)

Returns a hash for the specified password string. By default, hash is generated using PHP function md5. If configuration file wa-config/SystemConfig.class.php contains information about user-defined function wa_password_hash (read more), then that function is used for generating password hash instead of md5.

Parameters

  • $password

    Password string.

Example

waContact::getPasswordHash('6-~Md>vW);[&_3ue')

Result

09e9f44d40c72f889769f0d548b4e405

public function getPhoto ($width = null, $height = null)

Returns a contact's photo URL.

Parameters

  • $width

    Image width, handled exactly as described for method getPhotoUrl.

  • $height

    Image height, handled exactly as described for method getPhotoUrl.

Example

$contact = new waContact(); //create a new contact, without a photo
$contact->getPhoto(); //for contacts without a photo, the URL of the default userpic is returned

Result

/wa-content/img/userpic96.jpg

Example

$contact = new waContact(123); //get information about an existing contact
$contact->getPhoto(); //get the URL of this contact's photo

Result

/wa-data/public/contacts/photo/1/1343144519.96x96.jpg

public static function getPhotoUrl ($id, $ts, $width = null, $height = null)

Returns the photo URL of the specified contact.

Parameters

  • $id

    Contact id.

  • $ts

    Contact photo id stored in contact's photo property. If not specified, the URL of the default userpic is returned.

  • $width

    Image width. Accepted are integer values or string value original, which requires that method must return the original image originally uploaded from a user's computer for the specified contact. If not specified, the default value 96 is used.

  • $height

    Image height. Integer values are accepted. If not specified, the integer value specified for the $width parameter will be used.

Example

waContact::getPhotoUrl(1, 1915140120, 'original')

Result

/wa-data/public/contacts/photo/1/1915140120.original.jpg

public function getRights ($app_id, $name = null, $assoc = true)

Returns information about a contact's access rights configuration.

Parameters

  • $app_id

    Id of the app for which contact's access rights configuration must be returned.

  • $name

    String id of the access rights element available for the specified app. If not specified, all values of access rights for the current contact are returned. If % character is appended to the access rights element id, then the access rights values for that element are returned as an array. The array structure is defined by the value of the $assoc parameter.

  • $assoc

    Flag defining the structure of the returned array:

    • true (default value): multi-fields of access rights configuration elements are included in the returned array with access rights elements' ids as array keys and 1 as their values.
    • false: array keys are incremented starting from 0, array item values containing the ids of access rights configuration elements of access rights multi-fields enabled for a user.

Example

$contact = new waContact(123);
$contact->getRights('shop', 'orders');

Result

1

Example

$contact = new waContact(123);
$contact->getRights('shop', 'type%');

Result

Array
(
    [.1] => 1
    [.2] => 1
)
$contact = new waContact(123);
$contact->getRights('shop', 'type%', false);

Result

Array
(
    [0] => .1
    [1] => .2
)

public function getSettings ($app_id, $name = null, $default = null)

Returns the properties of a cointact relating to specified app.

Parameters

  • $app_id

    App id.

  • $name

    Id of the contact property associated with the specified app which must be returned. If not specified, an associative array of all properties of a contact is returned, which are associated with the specified app.

  • $default

    The default value which must be returned if the specified contact property for the specified app is not available. If contact property id is not specified for $default parameter, then the value of $default parameter is ignored.

Example

$contact = new waContact(123);
$contact->getSettings('blog');

Result

Array
(
    [blog_last_datetime] => 2013-12-03 13:52:33
    [type_items_count] => overdue:posts:comments
)

Example

$contact = new waContact(123);
$contact->getSettings('blog', 'type_items_count');

Result

overdue:posts:comments

public function getStatus()

Returns the status of a user: “online” or “offline”.

Example

$contact = new waContact(123);
$contact->getStatus();

Result

online

public function getTime()

Returns current data and time relative to a contact's locale and time zone configuration.

Example

$contact = new waContact(123);
$contact->getTime();

Result

12/03/2013 13:58

public function getTimezone()

Returns a contact's time zone value.

Example

$contact = new waContact(123);
$contact->getTimezone();

Result

America/New_York

public function isAdmin ($app_id = 'webasyst')

Returns information about whether a user has full (adminstrative) access rights to all installed apps or only one specified app.

Parameters

  • $app_id

    App id. If not specified, access rights for all installed apps are verified.

Example

$contact = new waContact(123);
$contact->isAdmin('blog');

Result

false // if a user does not have access to Blog app or has only limited access to that app, false is returned
//otherwise, method returns true

public function load ($format = false, $all = false)

Returns full information about a contact, which is stored in cache.

Parameters

  • $format

    Format string described for method get.

  • $all

    Flag requiring to return the values of fields marked as hidden in file wa-system/contact/data/fields.php.

Example

$contact = new waContact(123);
$contact->load('js', true);

public function save ($data = array(), $validate = false)

Saves a contact's data to the database.

Parameters

  • $data

    Associative array of contact property values.

  • $validate

    Flag requiring to validate property values. Default value is false.

Example

$contact = new waContact();
$contact->set('name', 'John Doe');
$contact->save();

public function set ($field_id, $value, $add = false)

Sets a value for the specified contact property.

Parameters

  • $field_id

    Contact property id.

  • $value

    Property value.

  • $add

    Flag requiring to add the specified value to existing values of a multi-field. If set to false, all existing values of the specified multi-field are deleted and replaced with the specified property value.

Example

$contact = new waContact();
$contact->set('name', 'John Doe');

public function setPhoto ($file)

Adds an image to an existing contact.

Parameters

  • $file

    Path to image file.

Example

$contact = new waContact(123);
$contact->setPhoto('path/to/imagefile.png');

public function setRight ($app_id, $name, $value)

Sets access rights for a user. If a user has administrative access rights for the specified app, then an attempt to change his access rights configuration using this method is ignored.

Parameters

  • $app_id

    Id of the app for which access rights of a contact must be set.

  • $name

    Access rights element id supported by the specified app.

  • $value

    Access rights value.

$contact = new waContact(123);
$contact->setRight('shop', 'orders', 1);

public function setSettings ($app_id, $name, $value = null)

Saves properties of the specified contact to the database.

Parameters

  • $app_id

    Id of the app for which a value of a contact property must be set.

  • $name

    Contact property id.

  • $value

    Contact property value.

Example

$contact = new waContact(123);
$contact->setSettings('shop', 'sidebar_width', 200);

public function validate ($data=array())

Validates the specified values of contact properties and returns an array of error messages.

Parameters

  • $data

    Associative array of contact property values.

Example

$data = array(
  'name'  => 'John Doe',
  'email' => 'domain.com' //incorrectly specified email address
);
$contact = new waContact();
$contact->validate($data);

Result

Array
(
    [email] => Array
        (
            [0] => Invalid email address
        )

)