Роуты, настройки, раскладка
Роуты и их имена
Ссылки стройте по имени, а не адресом: {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/ раскладываются два каталога — elements/ и lang/ — плюс заготовка config/pbauth.php. Что именно было положено, записано с хешами в core/App/.pbauth-installed.json, и по этому манифесту компонент и отличает свою копию от правленого вами файла.
Установка не перезаписывает ничего: там либо файла нет, либо он сайта.
Обновление с 1.1.1 даёт на каждый файл четыре исхода:
| Состояние файла | Что делает обновление | Лог |
|---|---|---|
| файла нет | кладёт поставочный | сводка INFO |
| байт в байт совпадает с поставочным либо числится в манифесте с прежним хешем | заменяет поставочным | сводка INFO |
| правлен сайтом | оставляет точно как есть | строка WARN на файл |
| свой, но перезаписать не удалось | оставляет как есть | строка ERROR на файл |
Файл, совпадающий с поставочным байт в байт, компонент считает своим даже без записи в манифесте — так подхватываются установки, сделанные до появления манифеста.
При удалении компонента стираются только те файлы, которые с тех пор не менялись; всё правленое остаётся сайту.
После обновления читайте лог
До 1.1.1 существующий файл не перезаписывался никогда, а значит исправление в поставочной вёрстке доезжало только до чистых установок: страница рисуется из копии в App/, а не из той, что в компоненте. Теперь нетронутые копии обновляются, а правленый вами файл остаётся вам и называется в логе. Эти строки WARN — и есть файлы, до которых правки версии не дошли.
Для 1.1.1 это не формальность: правки там про экранирование набранного посетителем. «Экранирование вывода и переход на 1.1.1».
Переход с версий до 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/: настройкой, событием или своим контроллером.
Исправление из changelog на сайте не появилось. Скорее всего оно в файле под core/App/elements/, который вы правили, и обновление его не тронуло. Найдите в логе строки WARN, начинающиеся с [pbAuth] App/ — по одной на такой файл, — и сверьте каждый с поставочным по тому же пути внутри core/components/pbauth/. См. «Экранирование вывода и переход на 1.1.1».
Имя со знаком < или & ломает вёрстку страницы. Печать без |escape в одном из ваших чанков. Fenom сам не экранирует, а $old_input — это присланное. Поставочные чанки исправлены в 1.1.1; ваши, если вы их правили, — нет.
Вместо текста ошибки форма печатает auth.что-то. Этого ключа нет в core/App/lang/<локаль>/auth.php. lang() читает только этот файл, отката к копии компонента нет, и ненайденный ключ печатается сам собой. В 1.1.1 добавлен username_forbidden_chars — если файл надписей правленый, допишите его руками.
После обновления в профиле не удаляется аватар. Ваш form.profile.tpl всё ещё присылает name="photo". С 1.1.1 поле называется delete_photo, и кнопка должна ставить ему 1.
Кнопки соцсети не появились. Показываются только настроенные провайдеры — проверьте 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.