README

PHP库，用于开发Yandex.Alice技能

内容

1. 版本历史 / TODO
2. 使用示例
3. 属性描述
   • request - 包含用户请求的信息；
   • response - 包含对用户请求的响应数据；
   • users_dir - 用户数据目录的名称；
   • sentences - 分析整个句子，而不是单个单词；
4. 方法描述
   • 构造函数 - 创建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 - 为 Google Chatbase 设置 handled 标志的值；
   • finish - 执行一些准备程序并向 Яндекса.Диалогы 发送响应；
5. 内置标签
6. 使用的库

待办事项

示例

使用库的示例位于 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 - 用户请求的数据。多维度数组（见此处）。非必须。默认值：php://input 的解码 json。

$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 的指针。

$action - 需要传递控制的函数名。字符串。必填参数。

function new_session_action($alice) {
	...
	some code
	...
}
$alice->bind_new_action('new_session_action');

bind_words_action

public function bind_words_action(array $words, string $action): bool

将指定的函数与用户请求中找到的指定单词的事件相关联。传入的函数将传递指向 $this 的指针和发现单词的数组。

$words - 要查找的单词（小写）。数组。必填参数；

$action - 需要传递控制的函数名。字符串。必填参数。

function find_word_action($words, $alice) {
	...
	some code
	...
}
$alice->bind_words_action(['яблоко', 'груша', 'апельсин'], 'find_word_action');

bind_percentage_action

public function bind_percentage_action(array $words, int $percentage, string $action): bool

将指定的函数与用户请求中超过（或等于）指定百分比找到单词的事件相关联。不考虑大小写。传入的函数将传递指向 $this 的指针和找到的百分比。

$words - 搜索的单词。元素也可以是数组 - 在这种情况下，数组内部任何匹配都被视为整个数组的匹配。数组。必须参数；

$percentage - 达到指定函数执行的百分比值。数字。必填参数；

$action - 需要传递控制的函数名。字符串。必填参数。

function percentage_word_action($percent, $alice) {
	...
	some code
	...
}
$alice->bind_percentage_action([['яблоко', 'груша'], 'апельсин'], 75, 'percentage_word_action');

bind_sentence_action

public function bind_sentence_action(string $text, int $percentage, string $action): bool

将指定的函数与超过（或等于）指定百分比的句子相似度事件相关联。传入的函数将传递指向 $this 的指针和找到的百分比。根据属性 sentences 的值，方法要么分析整个句子，要么将其分解成单个单词进行比较。

$text - 用于比较相似度的句子。字符串。必填参数；

$percentage - 达到指定函数执行的百分比值。数字。必填参数；

$action - 需要传递控制的函数名。字符串。必填参数。

function suggestion_action($percent, $alice) {
	...
	some code
	...
}
$alice->bind_sentence_action('Очистить список покупок', 75, 'suggestion_action');

bind_template_action

public function bind_template_action(array $patterns, string $action): bool

将指定的函数与用户短语与指定模板匹配的事件相关联。传入的函数将传递指向 $this 的指针和包含模式名称作为键的关联数组，其值包含找到的结果。

$patterns - 搜索模板的数组。详细信息请参阅方法 get_template_text 的说明。数组。必填参数。

$action - 需要传递控制的函数名。字符串。必填参数。

function template_action($patterns, $alice) {
	...
	// $patterns['name'] будет содержать названное пользователем имя
	...
}
$alice->bind_template_action(['Меня зовут {name:word}', 'Мое имя {name:word}'], 'template_action');

bind_default_action

public function bind_default_action(string $action): bool

将指定的函数与没有其他动作的事件相关联。非常适合处理用户短语未识别的情况。传入的函数将传递指向 $this 的指针。

$action - 需要传递控制的函数名。字符串。必填参数。

function default_action($alice) {
	...
	some code
	...
}
$alice->bind_default_action('default_action');

add_button

public function add_button(string $title, string $url=null, array $payload=null, bool $hide=false): bool

向用户的回答选项添加按钮。

$title - 按钮文本，在按钮被点击时将发送给技能。可以使用 内置标签。字符串。必填参数；

$url - 按钮应打开的 URL。字符串。非必需。默认值：null。

$payload - 雅典.对话应发送到处理器的任意数据，如果按下此按钮。数组。非必需。默认值：null。

$hide - 表示按钮在下一个用户回复后需要移除的标志。逻辑型。非必需。默认值：false。

$alice->add_button('Открой Яндекс', 'http://yandex.ru');
$alice->add_button('Сделать заказ', null, ['item' => 42, 'price' => 100], true);

add_message

public function add_message(string $message, string $tts=null): bool

将消息添加到回复列表。在发送前会自动选择一个随机选项。

$message - 要发送的消息文本。可以使用 内置标签。字符串。必需参数；

$tts - 用于语音播报的消息文本表示（查看这里）。可以使用 内置标签。可以使用 声音。字符串。非必需。默认值：$message。

$alice->add_message('Среди этих двух сообщений');
$alice->add_message('Будет выбрано только одно', 'уже выбрано только одно');

get_user_data

public function get_user_data(string $name): string

从用户数据中获取变量的值。

$name - 需要获取值的变量名。字符串。必需参数；

$user_name = $alice->get_user_data('name');

set_user_data

public function set_user_data(string $name, mixed $value): bool

在用户数据中设置变量的值。

$name - 需要设置的变量名。字符串。必需参数；

$value - 需要设置的变量值。如果设置为 null，则变量将被删除。任何类型。必需参数；

$alice->set_user_data('name', 'Иван');
$alice->set_user_data('items', ['Яблоки', 'Бананы', 'Молоко']);
$alice->set_user_data('notes', null);

get_session_data

public function get_session_data(string $name): string

从用户会话中获取变量的值。

$name - 需要获取值的变量名。字符串。必需参数；

$action = $alice->get_session_data('action');

set_session_data

public function set_session_data(string $name, mixed $value): bool

在用户会话中设置变量的值。

$name - 需要设置的变量名。字符串。必需参数；

$value - 需要设置的变量值。如果设置为 null，则变量将被删除。任何类型。必需参数；

$alice->set_session_data('action', 'start');
$alice->set_session_data('progress', ['step' => 2, 'place' => 'home']);
$alice->set_session_data('items', null);

end_session

public function end_session(): bool

结束与用户的对话。

$alice->end_session();

use_phpmorphy

public function use_phpmorphy(string $dicts_dir, string $language='ru_RU')

启用使用 phpMorphy 库。您也可以使用 $alice->phpmorphy 对象直接调用库的本地方法。任何时候都可以通过将 $alice->phpmorphy 属性设置为 null 来禁用此功能。

$dicts_dir - 存储词典的目录路径。字符串。必需参数。

$language - 要使用词典的语言。指定为 ISO3166 国家代码和 ISO639 语言代码的组合（ru_RU, uk_UA, en_EN, de_DE 等）。字符串。非必需。默认值："ru_RU"。

$alice->use_phpmorphy('vendor/umisoft/phpmorphy/dicts/');

use_yametrika

public function use_yametrika(string $counter_id)

启用使用 Яндекс.Метрика 服务。数据在调用 finish 方法时传递。

$counter_id - 在服务个人账户中获得的计数器 ID。字符串。必需参数。

$alice->use_yametrika('YOU_COUNTER_ID');

yametrika_rgoal

public function yametrika_rgoal(string $target): bool

在雅虎·统计中传输达成目标的信息。详情请参阅服务官方文档。

$target - 目标标识符。字符串。必填参数。

$alice->yametrika_rgoal('my_target');

use_chatbase

public function use_chatbase(string $api_key)

启用Google Chatbase服务。数据在调用finish方法时传输。

$api_key - 在服务个人账户中获得的API密钥。字符串。必填参数。

$alice->use_chatbase('YOU_CHATBASE_API_KEY');

chatbase_handled

public function chatbase_handled(bool $handled=true): bool

设置Google Chatbase的handled标志值。建议用这种方法标记用户请求未被识别或导致错误的情况。如果不调用此方法，则默认handled = false。

$handled - 要设置的handled的值。布尔值。非必填。默认值：true。

$alice->chatbase_handled();

finish

public function finish(bool $return=false): bool

执行一些准备步骤并发送响应到雅虎·对话。

$return - 返回响应（而不是输出到屏幕）。布尔值。非必填。默认值：false。

$alice->finish();

内置标签

某些方法（例如add_button和add_message）允许使用内置标签

[word1|word2|...|wordN] - 从所列字符串中随机选择一个字符串；

[date:format] - 当前日期/时间，按format格式（见date()函数描述）显示；

使用的库

phpMorphy: https://github.com/Umisoft/phpmorphy

Chatbase PHP: https://gitlab.com/bhavyanshu/chatbase-php

Server YaMetrika (分支): https://github.com/avdeevsv91/server_yametrika

CRC (由Philip Burggraf): https://github.com/pburggraf/CRC