Установить и показать формы

Эта страница — для вёрстки. Всё, что ниже, делается в шаблоне MODX и в .tpl-файлах; PHP начинается только на следующей странице, и то двумя строчками.

Установка

1. Поставьте PageBlocks 3.x — без него компонент выключится с записью в лог.
2. Приложения → Установщик → Загрузить дополнения, найти и установить pbAuth.
3. Система → Настройки системы, фильтр pageblocks. Настройка pageblocks_routing должна стоять в Route Only или Full API.
4. Там же включите pageblocks_load_scripts — формы начнут отправляться без перезагрузки, а ошибки подсвечиваться прямо в полях.
5. Почистите кэш сайта.

Проверка: откройте /login. Должна открыться страница с рабочей формой входа. Ресурс для неё создавать не надо — адрес поднимает роутер.

Миграция идёт отдельным шагом

Таблица нужна только для соцсетей, и пакет создаёт её при установке сам. Если на хостинге отключена функция exec(), резолвер честно скажет об этом в журнале — тогда примените миграцию руками:

php core/components/pageblocks/vendor/bin/phinx migrate \
    --configuration=core/components/pbauth/src/phinx.php --environment=production

Без таблицы работает всё, кроме входа через соцсети.

Что положил установщик

Куда	Что	Чьё
core/components/pbauth/	код, роуты, поставочные настройки, лексиконы	компонента — перезапишется при обновлении
core/App/elements/auth/	шаблоны-обёртки и чанки форм	ваше
core/App/lang/{ru,en,uk,de}/auth.php	все надписи	ваше
core/App/config/pbauth.php	заготовка настроек, вся закомментированная	ваше

«Ваше» здесь — не вежливость. Ни установка, ни обновление никогда не перезаписывают уже существующий файл в core/App/. Что именно положил установщик, записано с хешами в core/App/.pbauth-installed.json, и удаление компонента стирает только те файлы, которых вы не касались.

Кнопки «Войти» и «Регистрация» в шапке

Готовые чанки уже лежат, их надо только позвать из шаблона сайта. Вариантов два.

Обычные ссылки — ведут на отдельные страницы /login и /register:

{include 'file:auth/chunks/auth.tpl'}

Модальные окна — формы открываются поверх страницы:

{include 'file:auth/chunks/auth_modal.tpl'}

Оба чанка сами понимают, вошёл человек или нет: гостю показывают кнопки, вошедшему — аватар с именем и ссылку в профиль.

file: — это папка сайта

file:auth/chunks/auth.tpl означает core/App/elements/auth/chunks/auth.tpl. Источник по умолчанию задаётся настройкой pageblocks_elements_path.

Поменять их вид

Откройте core/App/elements/auth/chunks/auth.tpl и правьте как обычную вёрстку. Внутри всего две смысловые конструкции:

{auth}   ...то, что видит вошедший...   {/auth}
{guest}  ...то, что видит гость...      {/guest}

Ссылки не пишите руками — берите по имени, тогда они не сломаются, если адрес страницы поменяется:

<a href="{route 'pageLogin'}">Войти</a>
<a href="{route 'pageRegister'}">Регистрация</a>
<a href="{route 'pageProfile'}">Мой профиль</a>
<a href="{route 'logout'}">Выйти</a>

Полный список имён — в справочнике.

Страницы входа и регистрации

Страница собирается из двух файлов:

	Файл	Что это
обёртка	core/App/elements/auth/templates/auth.tpl	<html>, <head>, стили, общая рамка
форма	core/App/elements/auth/chunks/form.login.tpl	сама форма, вставляется внутрь обёртки

Обёрток две: auth.tpl (вход, регистрация, восстановление) и profile.tpl (профиль и смена пароля — там сбоку меню разделов).

Формы лежат рядом, по одной на действие:

core/App/elements/auth/chunks/
    form.login.tpl              вход
    form.register.tpl           регистрация
    form.forgotPassword.tpl     «забыли пароль»
    form.resetPassword.tpl      ввод нового пароля по ссылке из письма
    form.changePassword.tpl     смена пароля в профиле
    form.confirmPassword.tpl    подтверждение пароля
    form.resendVerification.tpl повторная отправка ссылки подтверждения
    form.twoFactorChallenge.tpl ввод кода при входе
    form.twoFactor.tpl          подключение и отключение кода в профиле
    form.socialEmail.tpl        дозапрос почты, если соцсеть её не дала
    form.profile.tpl            редактирование профиля
    social.buttons.tpl          кнопки входа через соцсети
    social.accounts.tpl         привязанные сети в профиле
    modals/                     те же формы для модальных окон
    email.verifyEmail.tpl       письмо со ссылкой подтверждения
    email.resetPassword.tpl     письмо для сброса пароля

В шаблон-обёртку приходят две переменные: $title — заголовок страницы и $form — имя чанка с формой (например form.login). Подключается форма так:

{set $chunkPath = 'file:auth/chunks/' ~ $form}
{include $chunkPath}

Что обязательно у поля формы

Правя форму, сохраните у каждого поля три вещи — иначе оно останется рабочим, но перестанет вести себя по-человечески:

<div class="form-group mb-3">
    <label class="mb-2" for="email">Почта</label>
    <input type="email" name="email" id="email"
           class="form-control{if $errors.email} is-invalid{/if}"
           value="{$old_input.email}" required>
    <span class="invalid-feedback" data-error="email">{$errors.email}</span>
</div>

Что	Зачем
name="email"	под этим именем поле придёт на сервер
{$errors.email} и data-error="email"	сюда попадёт текст ошибки; data-error нужен скрипту, чтобы подставить её без перезагрузки
{$old_input.email}	чтобы при ошибке введённое не стёрлось

Ошибки не показываются

Почти всегда — одно из двух: у поля нет {$errors.имя} и data-error="имя", либо выключена настройка pageblocks_load_scripts.

Подменить одну форму

Свою форму регистрации, а остальные оставить как есть: положите свой чанк рядом и назовите его в core/App/config/pbauth.php.

<?php

return [
    'forms' => [
        'register' => 'my.register',   // core/App/elements/auth/chunks/my.register.tpl
    ],
];

А если ваш шаблон рисует форму сам и переменная $form ему не нужна:

'forms' => ['profile' => null],

Свой шаблон вместо поставочного

Если у вас уже есть свой шаблон страницы — не правьте поставочный файл, укажите свой:

'views' => [
    'auth'    => 'file:templates/my-auth',      // core/App/elements/templates/my-auth.tpl
    'profile' => 'file:templates/my-profile',
],

Обёрток всего две, но отдельной странице можно назначить свою — ключ с именем действия перебивает общий:

'views' => [
    'profile'    => 'file:templates/my-profile',   // все страницы профиля
    'two_factor' => 'file:auth/templates/profile', // а эта — по-своему
],

Пригождается, когда шаблон профиля на сайте самодостаточный и $form не подставляет, а какой-то странице форма всё-таки нужна.

Писать нужно только отличия

Файл настроек склеивается с поставочным: словари дополняются по ключам, списки заменяются целиком. Перечислять все forms ради одной подмены не надо. Подробности — «Файл настроек».

Тексты и переводы

Все надписи — в core/App/lang/ru/auth.php, обычный PHP-массив:

<?php

return [
    'login_title' => 'Вход',
    'register_title' => 'Регистрация',
    'register_success' => 'Проверьте почту — мы отправили ссылку для подтверждения',
];

В шаблоне надпись зовут {lang 'auth.login_title'}, в PHP — lang('auth.login_title').

Языков четыре: ru, en, uk, de. Новый ключ добавляйте во все — иначе на другом языке вместо текста покажется сам ключ.

Не путайте с лексиконом

core/components/pbauth/lexicon/ — это подписи настроек и кнопок в админке MODX. Они принадлежат компоненту и перезаписываются при обновлении.

Если письмо с подтверждением не дошло

После регистрации человек получает письмо со ссылкой и, пока не перешёл по ней, войти не может. Письма теряются постоянно: спам, опоздание, опечатка в адресе.

Для этого есть страница /resend-verification — она уже подключена, ссылка на неё стоит внизу формы входа.

Ответ формы всегда одинаковый, независимо от того, нашёлся адрес или нет и подтверждён ли он. Иначе по этой форме можно было бы перебором выяснять, какие адреса на сайте зарегистрированы. Так же ведёт себя «забыли пароль».

Две формы не взаимозаменяемы

Восстановление пароля работает только для подтверждённых аккаунтов, а повторная отправка — только для неподтверждённых. MODX хранит оба одноразовых ключа в одном поле remote_key, и если бы формы пересекались, выданная ссылка убивала бы предыдущую.

Правка не видна

Почистите кэш MODX и обновите страницу через Ctrl+F5. Если правка исчезла совсем — скорее всего она была в файле внутри core/components/pbauth/: там перезаписывается всё.