README

PHP фреймворк для ботов VK

Мощная PHP библиотека для создания ботов ВКонтакте.
Поддержка VK API, LongPoll, Callback, OAuth2, клавиатур и медиа.

Ключевые особенности

Помимо полной поддержки VK API, SimpleVK предоставляет высокоуровневые инструменты и архитектурные решения, которые кардинально ускоряют и упрощают разработку.

PSR-{4,11,16} совместимость
Современная архитектура на Атрибутах: Организуйте код декларативно с помощью PHP 8 Атрибутов. Назначайте обработчики команд, кнопок и middleware так же, как в больших фреймворках (Laravel/Symfony).
Конструктор ботов: Создавайте сложные сценарии, команды и многоуровневые клавиатуры в читабельном цепочном стиле.
Продвинутая система отладки: Получайте подробные отчеты об ошибках с отформатированным трейсом и проблемным участком кода прямо в личные сообщения ВКонтакте.
Модуль массовых рассылок: Отправляйте сообщения с вложениями по всем диалогам или чатам в несколько строк кода.
Умные упоминания (placeholder’ы): Вставляйте теги в сообщения и библиотека сама заменит их на красивые кликабельные упоминания.
Обработка команд: Настраивайте триггеры на текст или регулярные выражения и легко извлекайте параметры из сообщений.

Полная поддержка VK API

SimpleVK предоставляет удобный доступ ко всем стандартным элементам VK API

Long Poll API (для User и Bots)
Callback API
Streaming API
Загрузка медиа: Фото, видео, документы, голосовые сообщения
Клавиатуры: Inline, прикрепленные, карусели
Кнопки: Текстовые, callback, URL, оплата, геолокация
Авторизация (OAuth): Упрощенная работа с токенами

Надежность и автоматизация из коробки

Вам не нужно думать о типичных проблемах VK API — SimpleVK решает их автоматически.

Защита от дублей: Игнорирование дублирующихся событий и повторных событий при долгой обработке.
Стабильность соединения: Повторные запросы к API при ошибках сети и сбоях/лимитах API.
Корректность данных: Встроенная обработка невалидных JSON и других ошибок API.
Разбитие длинных сообщений: Красиво разбивает сообщения выше 4096 символов на несколько частей.

Установка через Composer (Рекомендуемый)

composer require digitalstars/simplevk

Установка из архива

Для окружений, где невозможно использовать Composer.

Скачайте ZIP-архив SimpleVK-vX.Y.Z.zip из раздела Assets последнего релиза
Распакуйте его в ваш проект. Папка vendor уже содержит всё необходимое.

Проверка готовности сервера

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

<?php
require_once __DIR__ . '/vendor/autoload.php';
\DigitalStars\SimpleVK\Diagnostics::run();

Важно: Запускайте скрипт в той же среде, где будет работать ваш бот.

Callback бот? — Откройте скрипт в браузере.
LongPoll бот? — Выполните скрипт через консоль (CLI).

Быстрый старт

Вызов метода VK API

<?php
require_once __DIR__ . '/vendor/autoload.php';
use DigitalStars\SimpleVK\SimpleVK;
$vk = SimpleVK::create(ТОКЕН, '5.199'); 
//возвращает сразу по ключу 'response' из ответа
$data = $vk->request('users.get', [
    'user_ids' => 1,
    'fields' => ['screen_name']
]);

Простой Callback

<?php
require_once __DIR__ . '/vendor/autoload.php';
use DigitalStars\SimpleVK\SimpleVK;
$vk = SimpleVK::create(ТОКЕН, '5.199')->setConfirm(STR); //STR - строка подтверждения сервера
$vk->setUserLogError(ВАШ_VK_ID); //логгер ошибок в личку
$data = $vk->initVars($peer_id, $user_id, $type, $message); //инициализация переменных из события
if($type == 'message_new') {
    if($message == 'Привет') {
        $vk->msg('Привет, ~!fn~')->send();
    }
}

Простой LongPoll / User LongPoll

Если указать токен группы - будет LongPoll.
Если указать токен пользователя - User LongPoll.
А еще можно указать логин и пароль от аккаунта:
new LongPoll(ЛОГИН, ПАРОЛЬ, '5.199');
Но советую создать токен вот по этому гайду

<?php
require_once __DIR__ . '/vendor/autoload.php';
use DigitalStars\SimpleVK\LongPoll;
$vk = LongPoll::create(ТОКЕН, '5.199');
$vk->setUserLogError(ВАШ_VK_ID); //логгер ошибок в личку
$vk->listen(function () use ($vk) {
    $data = $vk->initVars($peer_id, $user_id, $type, $message); //инициализация переменных из события
    if($type == 'message_new') {
        if($message == 'Привет') {
            $vk->msg('Привет, ~!fn~')->send();
        }
    }
});

Минимальный Бот на конструкторе (Callback)

<?php
require_once __DIR__ . '/vendor/autoload.php';
use DigitalStars\SimpleVK\Bot;
$bot = Bot::create(ТОКЕН, '5.199');
$bot->cmd('img', '!картинка')->img('cat.jpg')->text('Вот твой кот');
$bot->run(); //запускаем обработку события

Минимальный Бот на конструкторе (LongPoll)

<?php
require_once __DIR__.'/vendor/autoload.php';
use DigitalStars\SimpleVK\{Bot, LongPoll};
$vk = LongPoll::create(ТОКЕН, '5.199');
$bot = Bot::create($vk);
$bot->cmd('img', '!картинка')->img('cat.jpg')->text('Вот твой кот');
$vk->listen(function () use ($bot) {
    $bot->run(); //запускаем обработку события
});

Бот с обработкой Команд на конструкторе (Callback)

<?php
require_once __DIR__.'/vendor/autoload.php';
use DigitalStars\SimpleVK\{Bot, SimpleVK as vk};
$vk = vk::create(ТОКЕН, '5.199');
$vk->setUserLogError(ID); //ID - это id vk, кому бот будет отправлять все ошибки, возникшие в скрипте
$bot = Bot::create($vk);
//отправит картинку с текстом
$bot->cmd('img', '!картинка')->img('cat.jpg')->text('Вот твой кот');
//обработка команды с параметрами
$bot->cmd('sum', '!посчитай %n + %n')->func(function ($msg, $params) {
    $msg->text($params[0] + $params[1]);
});
//обработка команды по регулярке
$bot->preg_cmd('more_word', "!\!напиши (.*)!")->func(function ($msg, $params) {
    $msg->text("Ваше предложение: $params[1]");
});
$bot->run();

Бот с обработкой Кнопок на конструкторе (Callback)

<?php
require_once __DIR__.'/vendor/autoload.php';
use DigitalStars\SimpleVK\{Bot, SimpleVK as vk};
$vk = vk::create(ТОКЕН, '5.199');
$vk->setUserLogError(ID); //ID - это id vk, кому бот будет отправлять все ошибки, возникшие в скрипте
$bot = Bot::create($vk);
$bot->redirect('other', 'first'); //если пришла неизвестная кнопка/текст, то выполняем first
$bot->cmd('first')->kbd([['fish', 'cat']])->text('Выберите животное:'); //срабатывает при нажатии кнопки Начать
$bot->btn('fish', 'Рыбка')->text('Вы выбрали Рыбку!')->img('fish.jpg');
$bot->btn('cat', 'Котик')->text('Вы выбрали Котика!')->img('cat.jpg');
$bot->run();

Режим отладки и фоновая обработка

VK Callback API требует, чтобы ваш скрипт ответил "ok" и завершился в течение нескольких секунд. В противном случае VK посчитает запрос неудавшимся и начнет его повторять.

По умолчанию SimpleVK решает эту проблему, немедленно отправляя "ok" и разрывая соединение с VK, после чего продолжает выполнять ваш код в фоновом режиме.

Куда смотреть, если что-то не так?

Важно понимать, что при таком подходе стандартные логи запросов в интерфейсе VK не будут содержать ошибок вашего PHP-скрипта, потому что для VK запрос всегда будет выглядеть успешным.

Логи сервера (Главный источник)
Все ошибки (возникшие до и после отправки "ok") будут записаны в error.log вашего веб-сервера. Это основной источник информации для отладки.
Уведомления в ВК
Если вы настроили обработчик ошибок ->setUserLogError(), он дополнительно отправит вам отформатированное сообщение об ошибке в ЛС.

Important

setUserLogError перехватит только те ошибки, которые произошли после его инициализации.

Что делать, если нет доступа к логам?

Если у вас возникает проблема до вызова new SimpleVK(), но вы не можете посмотреть логи сервера, воспользуйтесь режимом отладки. Он отключает немедленную отправку "ok", позволяя ошибке проявиться и стать видимой в логах запросов VK или при запуске скрипта в браузере.

Чтобы диагностировать проблему, поместите этот код в самое начало вашего файла-обработчика:

// Включаем отображение и логирование абсолютно всех ошибок
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');

// Подключаем автозагрузчик и другие файлы
require_once 'vendor/autoload.php';
// ...

// Отключаем немедленную отправку "ok"
SimpleVK::disableSendOK(true);

// Далее ваш обычный код...
$vk = new SimpleVK('YOUR_TOKEN', '5.199');