yandex-dialogs-php

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

yandex-dialogs-php

★ 11 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# YANDEX-DIALOGS-PHP

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

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

1. [История версий / TODO](#todo)
 2. [Примеры использования](#%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B)
 3. [Описание свойств](#%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0)
 	+ [request](#request) - Содержит информацию о запросе пользователя;
	+ [response](#response) - Содержит данные ответа на запрос пользователя;
	+ [users_dir](#users_dir) - Имя каталога с данными пользователей;
	+ [sentences](#sentences) - Анализировать целые предложения, а не отдельные слова;
 4. [Описание методов](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B)
 	+ [Конструктор](#%D0%BA%D0%BE%D0%BD%D1%81%D1%82%D1%80%D1%83%D0%BA%D1%82%D0%BE%D1%80) - Создание объекта класса YandexDialog;
	+ [debug](#debug) - Начать сбор отладочной информации;
	+ [get_request](#get_request) - Получить информацию о запросе пользователя;
	+ [get_template_text](#get_template_text) - Получает часть текста на основе заданных шаблонов;
	+ [get_sentence_words](#get_sentence_words) - Разбивает предложение на массив слов;
	+ [get_plural_form](#get_plural_form) - Выбор слова с необходимым склонением для числительного;
	+ [words_percentage](#words_percentage) - Получить процентное содержание слов в массиве;
	+ [compare_words](#compare_words) - Сравнение двух слов на схожесть;
	+ [is_new_session](#is_new_session) - Проверка признака старта новой сессии;
	+ [is_cmd_start](#is_cmd_start) - Проверка наличия запроса, переданного вместе с командой активации навыка;
	+ [bind_new_action](#bind_new_action) - Связывает указанную функцию с событием начала нового диалога (новой сессии);
	+ [bind_words_action](#bind_words_action) - Связывает указанную функцию с событием нахождения одного из заданных слов в запросе пользователя;
	+ [bind_percentage_action](#bind_percentage_action) - Связывает указанную функцию с событием превышения заданного процентного нахождения слов в запросе пользователя;
	+ [bind_sentence_action](#bind_sentence_action) - Связывает указанную функцию с событием превышения (или равенства) заданной процентной схожести предложения;
	+ [bind_template_action](#bind_template_action) - Связывает указанную функцию с событием совпадения фразы пользователя и заданного шаблона;
	+ [bind_default_action](#bind_default_action) - Связывает указанную функцию с собитием отсутствия других действий;
	+ [add_button](#add_button) - Добавляет кнопку в варианты ответа пользователя;
	+ [add_message](#add_message) - Добавляет сообщение в список ответов;
	+ [get_user_data](#get_user_data) - Получить значение переменной из данных пользователя;
	+ [set_user_data](#set_user_data) - Установить значение переменной в данных пользователя;
	+ [get_session_data](#get_session_data) - Получить значение переменной из сессии пользователя;
	+ [set_session_data](#set_session_data) - Установить значение переменной из сессии пользователя;
	+ [end_session](#end_session) - Завершает диалог с пользователем;
	+ [use_phpmorphy](#use_phpmorphy) - Включает использование библиотеки phpMorphy;
	+ [use_yametrika](#use_yametrika) - Включает использование сервиса Яндекс.Метрика;
	+ [yametrika_rgoal](#yametrika_rgoal) - Передача информации о достижении цели в Яндекс.Метрике;
	+ [use_chatbase](#use_chatbase) - Включает использование сервиса Google Chatbase;
	+ [chatbase_handled](#chatbase_handled) - Устанавливает значение флага handled для Google Chatbase;
	+ [finish](#finish) - Производит некоторые подготовительные процедуры и отправляет ответ Яндекс.Диалогам;
 4. [Встроенные теги](#%D0%B2%D1%81%D1%82%D1%80%D0%BE%D0%B5%D0%BD%D0%BD%D1%8B%D0%B5-%D1%82%D0%B5%D0%B3%D0%B8)
 5. [Используемые библиотеки](#%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D1%83%D0%B5%D0%BC%D1%8B%D0%B5-%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA%D0%B8)

___
## TODO
| Описание изменений | Дата публикации 
|--|:--:|
|Первая публичная версия | **08.01.2019**
|Поддержка сервиса [Google Chatbase](#use_chatbase) | **09.01.2019**
|[Сохранение](#get_session_data)/[получение](#set_session_data) данных сессии | **05.02.2019**
|[Сохранение](#set_user_data)/[получение](#get_user_data) данных пользователя | **05.02.2019**
|Получение части текста по шаблону ([get_template_text](#get_template_text)) | **07.02.2019**
|Поддержка сервиса [Яндекс.Метрика](#use_yametrika) | **08.02.2019**
|Морфологический анализ слов с помощью [phpMorphy](#use_phpmorphy) | **20.02.2019**
|Расширение списка [встроенных тегов](#%D0%B2%D1%81%D1%82%D1%80%D0%BE%D0%B5%D0%BD%D0%BD%D1%8B%D0%B5-%D1%82%D0%B5%D0%B3%D0%B8) | **в работе**
|Отправка [сообщений с изображениями](https://tech.yandex.ru/dialogs/alice/doc/resource-upload-docpage/) | ---
|Поддержка сервиса [AppMetrica](https://appmetrica.yandex.ru/) | ---
|Поддержка сервиса [Google Analytics](https://analytics.google.com/) | ---
|Вложенные нелинейные сценарии | ---

## Примеры
Примеры использования библиотеки находятся в папке [examples](https://github.com/avdeevsv91/yandex-dialogs-php/tree/master/examples).

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

### request
Содержит информацию о запросе пользователя. Более подробно можно почитать в [официальной документации](https://tech.yandex.ru/dialogs/alice/doc/protocol-docpage/#request) к протоколу.

### response
Содержит данные ответа на запрос пользователя. Более подробно можно почитать в [официальной документации](https://tech.yandex.ru/dialogs/alice/doc/protocol-docpage/#response) к протоколу.

### users_dir
Имя каталога, содержащего файлы с данными пользователей (см. [get_user_data](#get_user_data) и [set_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()`

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

### get_request

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

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

`$data` - Данные запроса пользователя. Многомерный массив ([см.тут](https://tech.yandex.ru/dialogs/alice/doc/protocol-docpage/#request)). Не обязательно. По умолчанию: декодированный 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.