waContact

Работа с контактами

Содержание...

Контакт — это запись о персоне или организации в системном хранилище фреймворка. Для получения возможности управления контактом или получения информации о нем необходимо создать экземпляр класса 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 для отображения на веб-странице;
    • 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,
    ]