Контакт — это запись о персоне или организации в системном хранилище фреймворка. Для получения возможности управления контактом или получения информации о нем необходимо создать экземпляр класса waContact
, например:
$contact = new waContact($id); $contact_name = $contact->getName();
Методы
-
add
Добавляет дополнительное значение для указанного свойства контакта.
-
addToCategory
Добавляет контакт в указанную категорию.
-
delete
Удаляет контакт.
-
delSettings
Удаляет свойство контакта, относящееся к указанному приложению.
-
get
Возвращает значение свойства контакта.
-
getCache
Возвращает значение свойства контакта из кеша без обращения к базе данных.
-
getFirst
Возвращает первое значение множественного свойства контакта.
-
getId
Возвращает числовой идентификатор (
id
) контакта. -
getLocale
Возвращает локаль контакта.
-
getName
Возвращает имя (
name
) контакта. -
getPasswordHash
Возвращает хеш пароля.
-
getPhoto
Возвращает URL фотографии контакта.
-
getPhotoUrl
Возвращает URL фотографии указанного контакта.
-
getRights
Возвращает информацию о правах доступа контакта.
-
getSettings
Возвращает свойства контакта, относящиеся к указанному приложению.
-
getStatus
Возвращает статус контакта-пользователя.
-
getTime
Возвращает текущую дату и время с учетом локали и временной зоны контакта.
-
getTimezone
Возвращает временную зону контакта.
-
isAdmin
Возвращает информацию о том, имеет ли контакт-пользователь полные права доступа ко всему бекенду либо указанному приложению.
-
load
Возвращает полную информацию о контакте, хранящуюся в кеше.
-
save
Сохраняет информацию о контакте в базу данных.
-
set
Устанавливает значение для указанного свойства контакта.
-
setPhoto
Добавляет изображение для существующего контакта.
-
setRight
Устанавливает права доступа для контакта.
-
setSettings
Сохраняет параметры контакта для указанного приложения в базу данных.
-
validate
Проверяет корректность значений свойств контакта.
-
getEvent
Возвращает информацию о текущем статусе пользователя бекенда, установленном в системном календаре.
public function add ($field, $value)
Добавляет дополнительное значение для указанного свойства контакта.
Параметры
-
$field
Имя свойства.
-
$value
Значение свойства.
Пример
$contact = new waContact(); $contact->set('email', 'email1@domain.com'); $contact->add('email', 'email2@domain.com');
public function addToCategory ($category_id)
Добавляет контакт в указанную категорию. Применяется только к существующим контактам, хранящимся в базе данных.
Параметры
-
$category_id
Целочисленное значение id категории или строковое значение (только для системных категорий), в которую нужно добавить контакт.
Пример
$contact = new waContact(1); $contact->addToCategory(12); $contact->addToCategory('blog');
public function delete()
Удаляет контакт из базы данных.
Пример
$contact = new waContact(123); $contact->delete();
public function delSettings ($app_id, $name)
Удаляет из базы данных свойство контакта, относящееся к указанному приложению.
Параметры
-
$app_id
Идентификатор приложения.
-
$name
Строковый идентификатор свойства контакта.
Пример
$contact = new waContact(1); $contact->delSettings('blog', 'nickname');
public function get ($field_id, $format = null)
Возвращает значение свойства контакта в соответствии с указанным форматом.
Параметры
-
$field_id
Идентификатор свойства контакта.
-
$format
Строковое обозначение формата, в котором необходимо получить значение свойства. Допустимые значения:
- default: простое текстовое значение свойства; для множественных полей возвращается первое из имеющихся значений свойства контакта;
- default|top: для множественных полей возвращается первое из имеющихся значений свойства контакта, отформатированное средствами HTML для отображения на веб-странице;
- default|value: для указанного дочернего поля в составе множественного составного поля возвращается первое из имеющихся значений, предназначенное для отображения на веб-страницах (например, для дочернего поля 'address:country' отображается название страны вместо её идентификатора);
- value: простое текстовое значение свойства; для множественных полей возвращается массив имеющихся значений свойства контакта;
- html: полное значение свойства, отформатированное средствами HTML для отображения на веб-странице;
- html|top или js|top: для множественных полей возвращается массив полных значений, отформатированных средствами HTML для отображения на веб-странице;
- js: простое текстовое значение свойства; для множественных полей возвращается массив имеющихся значений свойства контакта со следующими основными элементами для каждого значения:
- value: значение элемента множественного поля, отформатированное средствами HTML для отображения на веб-странице
- data: простое значение элемента множественного поля в виде строки или массива
- формат не указан: простое текстовое значение свойства; для множественных полей возвращается массив имеющихся значений свойства контакта, каждый подмассив которого содержит элемент
value
с простым текстовым значением свойства, а также другие элементы, характерные для конкретного типа свойства контакта
Пример
$contact = new waContact(123); $contact->get('name');
Результат
Виктор Петров
Пример
$contact = new waContact(123); $contact->get('email', 'value');
Результат
[ [0] => email1@domain.ru [1] => email2@domain.ru ]
Пример
$contact = new waContact(123); $contact->get('url', 'js');
Результат
[ [0] => [ [value] => <a target="_blank" href="http://domain1.ru">domain1.ru</a><a target="_blank" href="http://domain1.ru"><i class="icon16 new-window"></i></a> [ext] => work [data] => http://domain1.ru ] [1] => [ [value] => <a target="_blank" href="http://domain2.ru">domain2.ru</a><a target="_blank" href="http://domain2.ru"><i class="icon16 new-window"></i></a> [ext] => personal [data] => http://domain2.ru ] ]
public function getCache ($field_id = null, $old_value = false)
Возвращает значение свойства контакта из кеша без обращения к базе данных.
Параметры
-
$field_id
Идентификатор свойства контакта. Если не указано, возвращается информация обо всех свойствах контакта.
-
$old_value
Флаг, обозначающий, нужно ли возвращать только значения свойств контакта, полученные из базы данных, игнорируя динамически добавленные значения. Если не указано, используется значение по умолчанию false — возвращать как значения, полученные из базы данных, так и значения, добавленные динамически.
Пример
//получаем и сохраняем в кеш информацию о контакте из базы данных $contact = new waContact(123); // динамически добавляем новые значения для поля 'email', в котором уже содержатся некоторые значения, хранящиеся в базе данных $contact->add('email', 'extra1@domain.ru'); $contact->add('email', 'extra2@domain.ru'); //получаем из кеша значения поля 'email': как полученные из базы данных, так и добавленные динамически $contact->getCache('email');
Результат
[ [0] => [ [value] => email1@domain.ru [ext] => work [status] => unknown ] [1] => [ [value] => email2@domain.ru [ext] => personal [status] => unknown ] [2] => [ [value] => extra1@domain.ru [ext] => [status] => unknown ] [3] => [ [value] => extra2@domain.ru [ext] => [status] => unknown ] ]
Пример
$contact = new waContact(123); $contact->add('email', 'extra1@domain.ru'); $contact->add('email', 'extra2@domain.ru'); //получаем из кеша значения поля 'email': только те, которые были получены из базы данных $contact->getCache('email', true);
Результат
[ [0] => [ [value] => email1@domain.ru [ext] => work [status] => unknown ] [1] => [ [value] => email2@domain.ru [ext] => personal [status] => unknown ] ]
public function getFirst ($field_id)
Возвращает первое значение множественного свойства контакта.
Параметры
-
$field_id
Идентификатор свойства контакта.
Пример
$contact = new waContact(123); $contact->getFirst('email');
Результат
[ [value] => email1@domain.ru [ext] => [status] => unknown ]
public function getId()
Возвращает числовой идентификатор (id) контакта.
Пример
$contact = new waContact(123); $contact->getId();
Результат
123
public function getLocale()
Возвращает локаль контакта.
Пример
$contact = new waContact(123); $contact->getLocale();
Результат
ru_RU
public function getName()
Возвращает имя (name
) контакта.
Пример
$contact = new waContact(123); $contact->getName();
Результат
Виктор Петров
public static function getPasswordHash ($password)
Возвращает хеш для указанного пароля. Для формирования хеша по умолчанию используется функция md5
. Если в конфигурационном файле wa-config/SystemConfig.class.php
определена пользовательская функция wa_password_hash
(подробнее об определении функции), то для формирования хеша используется она.
Параметры
-
$password
Строка с паролем.
Пример
waContact::getPasswordHash('6-~Md>vW);[&_3ue')
Результат
09e9f44d40c72f889769f0d548b4e405
public function getPhoto ($width = null, $height = null)
Возвращает URL фотографии контакта.
Параметры
-
$width
Ширина изображения. Обрабатывается так же, как в методе getPhotoUrl.
-
$height
Высота изображения. Обрабатывается так же, как в методе getPhotoUrl.
Пример
$contact = new waContact(); //создаем новый контакт — у него еще нет фотографии $contact->getPhoto(); //для контактов без фотографии возвращается URL аватара по умолчанию
Результат
/wa-content/img/userpic96.jpg
Пример
$contact = new waContact(123); //получаем информацию о существующем контакте $contact->getPhoto(); //получаем URL фотографии этого контакта
Результат
/wa-data/public/contacts/photo/1/1343144519.96x96.jpg
public static function getPhotoUrl ($id, $ts, $width = null, $height = null)
Возвращает URL фотографии указанного контакта.
Параметры
-
$id
Идентификатор контакта.
-
$ts
Идентификатор фотографии — хранится в свойстве контакта
photo
; если не указан, будет возвращен URL стандартного аватара контакта. -
$width
Ширина изображения. Допускаются целочисленные значения либо строковый идентификатор
original
, который обозначает, что необходимо вернуть оригинальное изображение, загруженное с компьютера пользователя для указанного контакта. Если не указано, то используется значение по умолчанию 96. -
$height
Высота изображения. Допускаются целочисленные значения. Если не указано, будет использовано целочисленное значение, указанное для параметра
$width
.
Пример
waContact::getPhotoUrl(1, 1915140120, 'original')
Результат
/wa-data/public/contacts/photo/1/1915140120.original.jpg
public function getRights ($app_id, $name = null, $assoc = true)
Возвращает информацию о правах доступа контакта-пользователя.
Параметры
-
$app_id
Идентификатор приложения, права доступа к которому необходимо получить.
-
$name
Строковый идентификатор прав доступа, определенный для указанного приложения. Если не указано, метод вернет все значения прав доступа для данного контакта. Если в конце идентификатора прав доступа добавлен символ %, то значения прав доступа для данного идентификатора будут получены в виде массива. Структура массива формируется в зависимости от значения параметра
$assoc
. -
$assoc
Флаг, использующийся для формирования массива значений множественных прав доступа:
- true (значение по умолчанию): в качестве ключей массива используются идентификаторы полей множественного права доступа, включенных для данного пользователя, а в качестве значений — число 1.
- false: ключи массива нумеруются автоматически начиная с 0, а в качестве значений элементов массива используются идентификаторы полей множественного права доступа, включенных для данного пользователя.
Пример
$contact = new waContact(123); $contact->getRights('shop', 'orders');
Результат
1
Пример
$contact = new waContact(123); $contact->getRights('shop', 'type%');
Результат
[ [.1] => 1 [.2] => 1 ]
$contact = new waContact(123); $contact->getRights('shop', 'type%', false);
Результат
[ [0] => .1 [1] => .2 ]
public function getSettings ($app_id, $name = null, $default = null)
Возвращает свойства контакта, относящиеся к указанному приложению.
Параметры
-
$app_id
Идентификатор приложения.
-
$name
Идентификатор свойства. Если идентификатор указан, метод возвращает значение такого свойства, связанного с указанным приложением. Если не указан, метод возвращает ассоциативный массив со значениями всех свойств контакта, связанных с приложением.
-
$default
Значение по умолчанию, возвращаемое в случае отсутствия значения для указанного свойства. Если идентификатор свойства в параметре
$default
не указан, то данный параметр игнорируется.
Пример
$contact = new waContact(123); $contact->getSettings('blog');
Результат
[ [blog_last_datetime] => 2013-12-03 13:52:33 [type_items_count] => overdue:posts:comments ]
Пример
$contact = new waContact(123); $contact->getSettings('blog', 'type_items_count');
Результат
overdue:posts:comments
public function getStatus()
Возвращает статус контакта-пользователя: «онлайн» или «оффлайн».
Пример
$contact = new waContact(123); $contact->getStatus();
Результат
online
public function getTime()
Возвращает текущую дату и время с учетом локали и временной зоны контакта.
Пример
$contact = new waContact(123); $contact->getTime();
Результат
03.12.2013 13:58
public function getTimezone()
Возвращает временную зону контакта.
Пример
$contact = new waContact(123); $contact->getTimezone();
Результат
Europe/Moscow
public function isAdmin ($app_id = 'webasyst')
Возвращает информацию о том, имеет ли контакт-пользователь полные права доступа («администратор») ко всему бекенду либо указанному приложению.
Параметры
-
$app_id
Идентификатор приложения. Если не указан, метод проверяет права доступа для всего бекенда.
Пример
$contact = new waContact(123); $contact->isAdmin('blog');
Результат
false // если у пользователя нет доступа к приложению «Блог» либо если у него ограниченные права к этому приложению //в противном случае метод вернет true
public function load ($format = false, $all = false)
Возвращает полную информацию о контакте, хранящуюся в кеше.
Параметры
-
$format
Идентификатор формата, описанный для метода get.
-
$all
Флаг, обозначающий, нужно ли включать в список возвращаемых значений поля, отмеченные как скрытые, в файле
wa-system/contact/data/fields.php
.
Пример
$contact = new waContact(123); $contact->load('js', true);
public function save ($data = [], $validate = false)
Сохраняет информацию о контакте в базу данных.
Параметры
-
$data
Ассоциативный массив значений свойств контакта.
-
$validate
Флаг, обозначающий, нужно ли выполнять валидацию значений. Значение по умолчанию — false.
Пример
$contact = new waContact(); $contact->set('name', 'Виктор Петров'); $contact->save();
public function set ($field_id, $value, $add = false)
Устанавливает значение для указанного свойства контакта.
Параметры
-
$field_id
Идентификатор свойства.
-
$value
Значение свойства.
-
$add
Флаг, обозначающий, нужно ли добавить значение к существующим значениям указанного множественного свойства либо удалить уже имеющиеся значения и вместо них установить указанное значение.
Пример
$contact = new waContact(); $contact->set('name', 'Виктор Петров');
public function setPhoto ($file)
Добавляет изображение для существующего контакта.
Параметры
-
$file
Путь к файлу изображения.
Пример
$contact = new waContact(123); $contact->setPhoto('path/to/imagefile.png');
public function setRight ($app_id, $name, $value)
Устанавливает права доступа для контакта-пользователя. Если пользователь обладает правами администратора для указанного приложения, то попытка изменить его права доступа с помощью этого метода будет проигнорирована.
Параметры
-
$app_id
Идентификатор приложения, для которого необходимо установить права доступа.
-
$name
Идентификатор прав доступа, поддерживаемый указанным приложением.
-
$value
Значение прав доступа.
$contact = new waContact(123); $contact->setRight('shop', 'orders', 1);
public function setSettings ($app_id, $name, $value = null)
Сохраняет произвольные параметры контакта, относящиеся к указанному приложению, в базу данных.
Параметры
-
$app_id
Идентификатор приложения, для которого необходимо установить значение свойства контакта.
-
$name
Идентификатор свойства.
-
$value
Значение свойства.
Пример
$contact = new waContact(123); $contact->setSettings('shop', 'sidebar_width', 200);
public function validate ($data = [])
Проверяет корректность указанных значений свойств контакта и возвращает массив сообщений об ошибках.
Параметры
-
$data
Массив свойств контакта.
Пример
$data = [ 'name' => 'Виктор Петров', 'email' => 'domain.ru' //допустим, email-адрес контакта указан неверно ]; $contact = new waContact(); $contact->validate($data);
Результат
[ [email] => [ [0] => Email-адрес введен неправильно ] ]
public function getEvent()
Возвращает информацию о текущем статусе пользователя бекенда, установленном в системном календаре.
Пример
(new waContact(12))->getEvent()
Результат
[ 'id' => '22', 'uid' => '1671206331-707275@mydomain.ru', 'create_datetime' => '2022-12-16 18:58:51', 'update_datetime' => '2022-12-16 18:58:51', 'contact_id' => '1', 'calendar_id' => '1', 'summary' => 'отпуск с 16 декабря по 23 декабря', 'description' => '', 'location' => '', 'start' => '2022-12-16 19:00:00', 'end' => '2022-12-23 20:00:00', 'is_allday' => '1', 'is_status' => '1', 'sequence' => '0', 'calendar_name' => 'Отпуск', 'status_bg_color' => NULL, 'status_font_color' => NULL, 'bg_color' => '#5bb75b', 'font_color' => '#ffffff', 'icon' => NULL, ]