What pbAuth is

pbAuth is login, registration, password recovery and a user profile for sites built on PageBlocks 3.x. It sits on top of MODX accounts: the component neither creates a user table of its own nor replaces modUser.

This is not a standalone application. Without PageBlocks the component writes an error to the log and switches itself off: routing, controllers, file templates, validation, mail, migrations and the template engine all come from there.

No routing, no URLs

pageblocks_routing must be set to Route Only or Full API. On the default value /login and /register answer "page not found", and it looks exactly as if the package failed to install.

What it does and what it does not

The component holds the login scenarios. Registration with e-mail confirmation and resending of the link, login by username, e-mail or phone, password recovery and change, password confirmation before a dangerous action, a profile with an avatar, two-factor, login through six social networks, impersonation by a manager, and the "one session per account" mode.

The markup belongs to the site. Twenty form chunks and two wrapper templates are placed into core/App/elements/auth/ on install and from that moment on belong to the site. The component never touches them again — not on update, not on uninstall, as long as the file has been changed.

The split is rigid for exactly the reason that makes it necessary at all: login forms on two different sites have nothing in common but the field names, and no amount of parameterisation covers that.

One result, two paths

// Markup — a chunk in the template header, links to ready-made pages
{include 'file:auth/chunks/auth.tpl'}

// Markup — editing the form itself, ordinary markup in an ordinary file
core/App/elements/auth/chunks/form.login.tpl

// Developer — behavior changes through a setting, code or your own controller
core/App/config/pbauth.php

Neither path runs through the other: the templater edits .tpl files and never opens PHP, the developer changes behavior and never touches the markup.

pbAuth has no snippets, and that is not an omission in the docs

In neighbouring components the markup track is a snippet: [[!pbProducts]], swap the chunk, done. Here it works differently: the /login, /register and /profile pages are served by the PageBlocks router, they need neither a resource nor a call in a template. The zero step therefore comes out even shorter than with a snippet — there is nothing to set up, the URL already answers.

The price is a different one: to change behavior you edit a PHP settings file, not a call parameter. If markup in your team has no access to the site's files, take that into account in advance: in pbAuth there is nowhere to pass &tpl=.

Why routes and controllers live in the component

Up to version 1.1.0 the installer laid routes and controllers out into core/App/, and the site edited them in place. That worked until the first update: a fix in the component's controller never reached the site, because it was the site's copy that was executed.

Now it is the other way round. The code lives in the component and gets updated, and everything the site used to change by editing a controller has become a setting: templates, validation rules, redirects, user groups, replacing the controller itself — all through core/App/config/pbauth.php.

The file App/routes/auth.php disables the whole component

As long as core/App/routes/ contains a file with exactly this name, pbAuth assumes the site stayed on the old scheme and registers none of its own URLs — otherwise the same URIs would be registered twice.

An update deletes this file if it matches the shipped one byte for byte. An edited one stays, and you have to delete it by hand, moving your changes into App/config/pbauth.php. Put your own routes in a file with any other name.

What a table of its own buys

Exactly one feature in the whole component requires a table of its own — linking social network accounts (pba_social_accounts). The "provider account → user" relation is looked up on every login, and looking it up inside JSON in the profile would mean scanning every user.

Everything else lives in MODX fields: the two-factor secret and the backup codes go into the profile's extended under the pbauth key, the one-time confirmation and reset keys into the standard remote_key.

Where to go next

• Quick start — install it, show the buttons and forms, adjust the markup. No PHP.
• Custom fields in forms — add a phone number, remove what you do not need, get to grips with the validation rules.
• The settings file — what you can change without writing a single line of logic.
• Events and your own code — listeners, your own controllers, your own routes, JSON for an SPA.
• Social networks, 2FA, impersonation — three large subsystems and how they are built.
• Reference — routes and their names, settings in the manager, the file layout, troubleshooting.