Роуты, настройки, раскладка
Роуты и их имена
Ссылки стройте по имени, а не адресом: {route 'pageProfile'} в шаблоне, route('pageProfile') в PHP. Тогда они не сломаются, если адрес поменяется.
| Адрес | Имя страницы (GET) | Имя отправки формы (POST) | Доступ |
|---|---|---|---|
/login | pageLogin | login | гость |
/register | pageRegister | register | гость |
/forgot-password | pageForgotPassword | forgotPassword | гость |
/reset-password/{token} | pageResetPassword | resetPassword (форма шлётся на /reset-password) | гость |
/resend-verification | pageResendVerification | resendVerification | гость |
/two-factor | pageTwoFactorChallenge | twoFactorChallenge | гость |
/confirm-password | pageConfirmPassword | confirmPassword | вошедший |
/profile | pageProfile | updateProfile | вошедший |
/profile/password | pageChangePassword | changePassword | вошедший |
/profile/two-factor | pageTwoFactorSettings | twoFactorEnable | вошедший |
/profile/two-factor/disable | — | twoFactorDisable | вошедший |
/profile/two-factor/backup-codes | — | twoFactorBackupCodes | вошедший |
/logout | logout | — | вошедший |
/verify-email/{token} | verifyEmail | — | любой |
/auth/{provider} | socialRedirect | — | любой |
/auth/{provider}/callback | socialCallback | socialCallbackPost | любой |
/auth-email | pageSocialEmail | socialEmail | гость |
/profile/social/{provider}/unlink | — | socialUnlink | вошедший |
/impersonate/{id} | impersonate | — | менеджер с sudo |
Почему у соцсетей нет guest
Те же адреса используются для привязки сети к уже открытому аккаунту, и контроллер сам разбирает, вход это или привязка. У /impersonate/{id} нет auth по обратной причине: на сайте посетитель может быть анонимом, а права проверяются по сессии менеджера.
Настройки в админке
Система → Настройки системы, раздел pbauth:
| Настройка | Значение по умолчанию | Зачем |
|---|---|---|
pbauth_user_page | users/{id} | адрес публичной страницы пользователя, {id} и {username}. Пусто — кнопки «Посмотреть на сайте» нет |
pbauth_recaptcha_service | Google reCAPTCHA | какой антиспам используется |
pbauth_recaptcha_public_key | пусто | Site key от Google reCAPTCHA v3 |
pbauth_recaptcha_secret_key | пусто | Secret key. Пока он пуст, reCAPTCHA не проверяется |
Ключи берутся в панели Google reCAPTCHA.
Настройки PageBlocks, без которых компонент не работает:
| Настройка | Нужное значение |
|---|---|
pageblocks_routing | Route Only или Full API |
pageblocks_load_scripts | включено — формы без перезагрузки и подсветка ошибок |
pageblocks_elements_path | откуда берётся file: (по умолчанию {core_path}App/elements/) |
События плагина
Плагин pbAuth должен быть прикреплён к двум системным событиям. Пакет делает это сам; вручную — только если компонент раскладывали файлами.
| Событие | Приоритет | Для чего |
|---|---|---|
OnHandleRequest | -10 | режим «один вход на учётную запись» |
OnManagerPageBeforeRender | — | кнопки на пользователя в менеджере |
Приоритет -10 не косметика: проверка сессии обязана пройти раньше, чем PageBlocks начнёт разбирать запрос.
Что где лежит
core/components/pbauth/ КОМПОНЕНТ — не трогать, перезапишется
src/ код
routes/ адреса страниц
config/defaults.php поставочные настройки (смотреть можно, править нет)
plugins/pbauth.php исходник плагина для системных событий MODX
lexicon/ подписи настроек и кнопок в админке
docs/ руководство и образец настроек
src/Database/migrations/ таблица привязок соцсетей
assets/components/pbauth/ КОМПОНЕНТ — не трогать
js/mgr/user.js кнопки на пользователя в менеджере
core/App/ ВАШЕ — правьте свободно
config/pbauth.php ваши настройки компонента
elements/auth/templates/ обёртки страниц
elements/auth/chunks/ формы и письма
lang/{ru,en,uk,de}/auth.php надписи
Events/Auth/ ваши классы на события
Http/Controllers/Auth/ ваши контроллеры (если понадобятся)
routes/ ваши адреса (файл НЕ должен называться auth.php)
.pbauth-installed.json манифест установщика, трогать не надоГде что хранится в базе
| Что | Где |
|---|---|
| привязки аккаунтов соцсетей | своя таблица pba_social_accounts |
| секрет второго фактора и хеши резервных кодов | extended профиля, ключ pbauth |
| ключ подтверждения почты и ключ сброса пароля | штатное поле remote_key MODX |
| аватар | photo профиля, файл по avatar_path |
| свои поля без колонок | extended профиля — классом на USER_SAVING |
Оба одноразовых ключа лежат в одном remote_key — это ограничение MODX, и из него следует разделение двух форм.
Обновление и удаление
При установке и обновлении компонент кладёт в core/App/ только те файлы, которых там ещё нет. Существующий файл не перезаписывается никогда.
Что именно было положено, записано с хешами в core/App/.pbauth-installed.json. При удалении компонента стираются только те файлы, которые с тех пор не менялись; всё правленое остаётся сайту.
Файл, совпадающий с поставочным байт в байт, компонент считает своим даже без записи в манифесте — так подхватываются установки, сделанные до появления манифеста.
Переход с версий до 1.1.0
До 1.1.0 роуты и контроллеры раскладывались в core/App/. Обновление удаляет App/routes/auth.php, если он байт в байт совпадает с поставочным; правленый остаётся, и тогда компонент не подаёт ни одного своего адреса — живут ваши роуты и ваши контроллеры в App/Http/Controllers/Auth/.
Чтобы перейти на схему компонента, перенесите правки в App/config/pbauth.php и удалите App/routes/auth.php руками. Подробности — в core/components/pbauth/docs/changelog.txt, раздел Upgrading.
Если что-то не работает
/login открывается как «страница не найдена». Проверьте pageblocks_routing — должна быть Route Only или Full API. Затем: нет ли в core/App/routes/ файла с именем auth.php — он выключает адреса компонента целиком. Потом почистите кэш.
Поле из формы не сохраняется. Скорее всего оно не объявлено в rules — всё, чего там нет, отбрасывается. Если объявлено, но всё равно не сохраняется, значит у него нет колонки в базе: нужен класс на USER_SAVING, см. «Свои поля».
Регистрация пропускает одинаковые логины или почты. В правиле написано unique:modUser вместо unique:users. Проверка ждёт имя таблицы, а не класс MODX, и по несуществующей таблице молча ничего не находит.
Логин из одних цифр не проходит max:30. В правиле нет string, и длина меряется как величина числа.
Ошибки формы не показываются. У поля должны быть {$errors.имя} и data-error="имя". И должна быть включена настройка pageblocks_load_scripts.
Правка в шаблоне не видна. Почистите кэш MODX и обновите страницу через Ctrl+F5.
Правка исчезла после обновления компонента. Вы правили файл внутри core/components/pbauth/ — там перезаписывается всё. Переносите правку в core/App/: настройкой, событием или своим контроллером.
Кнопки соцсети не появились. Показываются только настроенные провайдеры — проверьте client_id и client_secret (у Telegram — bot_name и bot_token) в social.providers, и почистите кэш. Если настроены, а кнопок нет — не применена миграция pba_social_accounts.
Провайдер отвечает «неверный адрес возврата». В настройках приложения у провайдера должно быть ровно https://ваш-сайт/auth/<провайдер>/callback, с тем же протоколом и без лишнего слэша на конце.
«Вход не завершился» после возврата от провайдера. Потерялась сессия: между переходом к провайдеру и возвратом она должна сохраниться. Обычно это разные адреса сайта (с www и без) либо слишком короткое время жизни сессии.
Приложение показывает не тот код. Почти всегда — разъехались часы на телефоне и на сервере. В приложении есть пункт «синхронизировать время»; если не помогает, поднимите two_factor_window до 2. Совсем не пускает — войдите резервным кодом.
Мой класс на событие не вызывается. Проверьте: метод называется именно handle; класс перечислен в listeners в core/App/config/pbauth.php; путь к файлу совпадает с namespace (PageBlocks\App\Events\Auth\X → core/App/Events/Auth/X.php). Ошибки внутри класса не роняют страницу — ищите их в логе MODX (core/cache/logs/error.log).
Кнопок в менеджере нет. В Система → Плагины должен быть плагин pbAuth с прикреплённым OnManagerPageBeforeRender.
single_session не выселяет. К плагину не прикреплено OnHandleRequest либо у него приоритет позже PageBlocks. Нужен -10.