README

PHP библиотека для разработки навыков Яндекс.Алисы

Содержание

История версий / TODO
Примеры использования
Описание свойств
- request - Содержит информацию о запросе пользователя;
- response - Содержит данные ответа на запрос пользователя;
- users_dir - Имя каталога с данными пользователей;
- sentences - Анализировать целые предложения, а не отдельные слова;
Описание методов
- Конструктор - Создание объекта класса YandexDialog;
- debug - Начать сбор отладочной информации;
- get_request - Получить информацию о запросе пользователя;
- get_template_text - Получает часть текста на основе заданных шаблонов;
- get_sentence_words - Разбивает предложение на массив слов;
- get_plural_form - Выбор слова с необходимым склонением для числительного;
- words_percentage - Получить процентное содержание слов в массиве;
- compare_words - Сравнение двух слов на схожесть;
- is_new_session - Проверка признака старта новой сессии;
- is_cmd_start - Проверка наличия запроса, переданного вместе с командой активации навыка;
- bind_new_action - Связывает указанную функцию с событием начала нового диалога (новой сессии);
- bind_words_action - Связывает указанную функцию с событием нахождения одного из заданных слов в запросе пользователя;
- bind_percentage_action - Связывает указанную функцию с событием превышения заданного процентного нахождения слов в запросе пользователя;
- bind_sentence_action - Связывает указанную функцию с событием превышения (или равенства) заданной процентной схожести предложения;
- bind_template_action - Связывает указанную функцию с событием совпадения фразы пользователя и заданного шаблона;
- bind_default_action - Связывает указанную функцию с собитием отсутствия других действий;
- add_button - Добавляет кнопку в варианты ответа пользователя;
- add_message - Добавляет сообщение в список ответов;
- get_user_data - Получить значение переменной из данных пользователя;
- set_user_data - Установить значение переменной в данных пользователя;
- get_session_data - Получить значение переменной из сессии пользователя;
- set_session_data - Установить значение переменной из сессии пользователя;
- end_session - Завершает диалог с пользователем;
- use_phpmorphy - Включает использование библиотеки phpMorphy;
- use_yametrika - Включает использование сервиса Яндекс.Метрика;
- yametrika_rgoal - Передача информации о достижении цели в Яндекс.Метрике;
- use_chatbase - Включает использование сервиса Google Chatbase;
- chatbase_handled - Устанавливает значение флага handled для Google Chatbase;
- finish - Производит некоторые подготовительные процедуры и отправляет ответ Яндекс.Диалогам;
Встроенные теги
Используемые библиотеки

TODO

Описание изменений	Дата публикации
Первая публичная версия	08.01.2019
Поддержка сервиса Google Chatbase	09.01.2019
Сохранение/получение данных сессии	05.02.2019
Сохранение/получение данных пользователя	05.02.2019
Получение части текста по шаблону (get_template_text)	07.02.2019
Поддержка сервиса Яндекс.Метрика	08.02.2019
Морфологический анализ слов с помощью phpMorphy	20.02.2019
Расширение списка встроенных тегов	в работе
Отправка сообщений с изображениями	---
Поддержка сервиса AppMetrica	---
Поддержка сервиса Google Analytics	---
Вложенные нелинейные сценарии	---

Примеры

Примеры использования библиотеки находятся в папке examples.

Свойства

Не рекомендуется прямое изменение свойств объектов класса YandexDialog. Делайте это через соответствующие методы.

request

Содержит информацию о запросе пользователя. Более подробно можно почитать в официальной документации к протоколу.

response

Содержит данные ответа на запрос пользователя. Более подробно можно почитать в официальной документации к протоколу.

users_dir

Имя каталога, содержащего файлы с данными пользователей (см. get_user_data и set_user_data). Строка. По умолчанию: 'users'.

Методы

Конструктор

public function __construct(string $version='1.0')

Создание объекта класса YandexDialog.

$version - Номер используемой версии протокола. Строка. Не обязательно. По умолчанию: '1.0'.

$alice = new YandexDialog('1.0');

debug

public function debug()

Начинает сбор отладочной информации (время выполнения скрипта, потребляемая память и др.), просмотреть которую можно в кабинете разработчика Яндекс.Диалоги, раздел "Тестирование" (блок "Последний запрос").

get_request

public function get_request(array $data=null): bool

Получить информацию о запросе пользователя.

$data - Данные запроса пользователя. Многомерный массив (см.тут). Не обязательно. По умолчанию: декодированный json из php://input.

$alice->get_request();

get_template_text

public function get_template_text(array $patterns, string $text=null): array

Получает часть текста на основе заданных шаблонов. Метод возвращает ассоциативный массив, в котором в качестве ключей выступают имена паттернов, а значения заполнены найденными результатами. Если поиск не удался (оригинальный текст не подходит под указанные шаблоны, либо шаблоны составлены с ошибкой), то метод возвращает false.

$patterns - Массив шаблонов поиска. Подробнее в примерах ниже. Массив. Обязательный параметр.

$text - Текст, в котором осуществляется поиск. Строка. Не обязательно. По-умолчанию: текст команды пользователя.

$text = 'Меня зовут Иван Иванов. Мне сейчас 25 лет.';

$name = $alice->get_template_text(['Меня зовут {name1:word}', 'Мое имя {name1:word}'], $text); // ['name1' => 'Иван']
// Если шаблон один, то можно передавать его строкой
$name = $alice->get_template_text('Меня зовут {name1:word}', $text); // ['name1' => 'Иван']
$name = $alice->get_template_text('Меня зовут {name2}.', $text); // ['name2' => 'Иван Иванов']
$age = $alice->get_template_text('Мне {*}{age:int} лет', $text); // ['age' => 25]
$matches = $alice->get_template_text('Меня зовут {name:word}{*}Мне {*}{age:int} лет', $text); // ['name' => 'Иван', 'age' => 25]
$results = $alice->get_template_text('{Меня зовут|Мое имя} {*}', $text); // []
$results = $alice->get_template_text('Привет! {*}', $text); // false

get_sentence_words

public function get_sentence_words(string $text): array

Разбивает предложение на массив слов в нижнем регистре.

$text - Исходный текст. Строка. Обязательный параметр;

$words = $alice->get_sentence_words('Привет! Меня зовут Иван.'); // ['привет', 'меня', 'зовут', 'иван']

get_plural_form

public function get_plural_form(int $number, array $words): string

Выбирает слово с необходимым склонением для указанного числительного из массива вариантов.

$number - Целое число, для которого необходимо подобрать слово снужным склонением. Обязательный параметр;

$words - Массив слов для выбора. Три элемента, соответствующие числам 1, 2 и 5. Обязательный параметр;

$number = 3;

echo $number . ' ' . $alice->get_plural_form($number, ['арбуз', 'арбуза', 'арбузов']); // 3 арбуза

words_percentage

public function words_percentage(array $words, array $tokens): int

Получить процентное содержание указанных слов в переданном массиве. Регистр не учитывается.

$words - Слова для поиска. Элементы так же могут быть массивами - в таком случае любое из совпадений внутри вложенного массива считается как совпадение всего массива. Массив. Обязательный параметр;

$tokens - Строки для сравнения. Массив. Обязательный параметр;

$percentage = $alice->words_percentage([['раз', 'один'], 'два', 'три'], ['три', 'четыре', 'пять']); // ~33%

compare_words

public function compare_words(string $first, string $second): bool

Сравнивает два слова. Регистр не учитывается.

$first - Первое слово для сравнения. Строка. Обязательный параметр;

$second - Второе слово для сравнения. Строка. Обязательный параметр;

if($alice->compare_words('ПрИвЕт', 'привет')) { // true
	...
}

is_new_session

public function is_new_session(): bool

Метод возвращает true, если текущий запрос является началом новой сессии.

if($alice->is_new_session()) {
	...
}

is_cmd_start

public function is_cmd_start(): bool

Метод возвращает true, если вместе с командой активации навыка был передан запрос. Команды активации, с которыми рекомендуется передавать такие запросы: «скажи», «попроси», «узнай у» и «спроси у».

if($alice->is_cmd_start()) {
	...
}

bind_new_action

public function bind_new_action(string $action): bool

Связывает указанную функцию с событием начала нового диалога (новой сессии). В вызываемую функцию передается указатель на $this.