bagnum / BA-TG-Sender
CI/CD
Реестр контейнеров и пакетов

03. Использование BA-TG-Sender.md

Отправка сообщений

BA_TelegramSender

Непосредственно отправку сообщения осуществляет класс BA_TelegramSender.

Простейший код для отправки:

$tgSender = new BA_TelegramSender();
$tgSender
	->setBotToken($bot_token)
	->sendMessage($chatID, $message)
	->sendFiles($chatID, $uploadedFiles);

или

$tgSender = new BA_TelegramSender();
$tgSender->setBotToken($bot_token);
$tgSender->sendMessage($chatID, $message);
$tgSender->sendFiles($chatID, $uploadedFiles);

Переменные из примера

$bot_token - токен телеграм-бота

$chatID - идентификатор чата, куда нужно отправить сообщение. Целое число: положительное - если чат персональный, отрицательное - если чат групповой.

$message - текст сообщения (строковой тип);

$uploadedFiles - массив с данными о загруженных файлах. Аналогичные данным массива $_FILES, но к информации о файле добавлено ещё поле ‘file_path’ - полный путь до файла на сервере.

Рекомендация

BA_TelegramSender рекомендуется использовать в связке с классами:

  • BA_FileUploader - выполнит всё, что связано с загрузкой файлов на сервер, в т.ч. - различные проверки. Составит перечень загруженных файлов в виде массива, который может быть использован в качестве второго параметра метода sendFiles.
  • BA_KeyValue_combinator - соберёт данные полей формы обратной связи и поможет превратить текст сообщения в удобный мини-отчёт.

Подробнее о методах этого класса

Загрузка файлов

BA_FileUploader

Для того, чтобы отправить файлы в Телеграм, из нужно загрузить на сервер, поместить в заданный каталог, проверить на допустимый тип и размер, переименовать (как минимум - заменив пробелы дефисами) и возможно удалить после отправки. Всё это делает класс BA_FileUploader.

$uploader = new BA_FileUploader();

$uploader
	->setFiles($_FILES)
	->setUploadDir(__DIR__.DIRECTORY_SEPARATOR.'uploads')
	->setRenameFiles('translit')
	->uploadFiles();

$uploadedFiles = $uploader->getUploadedArray();

Методом setUploadDir задайте папку для загрузки файлов.

Внимание! Транслитерация только символов русского языка! Другие кириллические языки данный метод не поддерживает.

В любом случае пробелы в имени файла будут заменены дефисами.

Массив возвращённый методом $uploader->getUploadedArray() можно передать для отправки в метод $tgSender->sendFiles() вторым параметром.

Класс позволяет задать допустимые типы файлов и будет отсеивать не состоящие в списке разрешённых.

Метод clearUploads удаляет с сервера файлы загруженные в текущую сессию. Таким образом, после отправки файлов можно “подчистить за собой”, удалив уже не нужное содержимое папки с загрузками.

Подробнее о методах этого класса

Комбинатор данных

BA_KeyValue_combinator

Как правило, при использовании формы обратной связи (например - “заказать обратный звонок”), требуется отправить админу или менеджеру некое уведомление, содержащее отчёт о заявке и какие данные получены. Желательно - удобный для восприятия. Для этой цели создан класс BA_KeyValue_combinator.

С помощью метода setField нужно задать, как название поля должно отобразиться в тексте сообщения. Вместо типового “name” и “address”, можно указать например: “Имя пользователя” и “Обратный адрес”. Третьим (необязательным) параметром передаётся значение этого поля.

Так-же значения полей можно передать через методы setValue (по одному) и setValues - массивом.

Пример кода:

$combinator = new BA_KeyValue_combinator();
$combinator
	->setField('name', 'Имя')
	->setField('phone', 'Телефон')
	->setValues($_POST)
	->setSeparator(': ');
$strings = $combinator->combineAll();

В результате получаем массив строк вроде:

Имя: Иван Телефон: +7999*******

Подробнее о методах этого класса

Проверка полей и фильтрация значений

Следующие классы не имеют прямого отношения к отправке сообщений в Телеграм, но могут пригодиться при работе с формами обратной связи.

Фильтрация данных формы

BA_RequestDataFilter

Обычно данные форм нужно фильтровать от тегов, спецсимволов и начальных пробелов. С данной библиотекой это делается одной командой.

$post = BA_RequestDataFilter::filter($_POST);

В данном примере фильтруются все поля глобального массива POST.

Подробнее о методах этого класса

Проверка значений полей

BA_FieldChecker

Иногда веб-разработчики специально создают на форме скрытые поля, которые должны содержать строго определенные значения или наоборот - оставаться пустыми.

Для таких случаев предназначен класс BA_FieldChecker.

Метод addRequiredValue добавляет в список допустимое значение для соответствующего поля. В примере ниже поле “secret” должно быть пустым:

$fieldChecker->addRequiredValue('secret', '');

if ($fieldChecker->checkData($_POST)) {
}

Метод checkData возвращает true - если проверка пройдена и в заданных полях переданного массива присутствуют допустимые значения. Если хотя-бы в одном из полей значение не соответствует допустимому, метод возвращает false.

Подробнее о методах этого класса