Your own fields in the forms
The most common task right after installation. Let's work through it with a phone number in registration.
A field that is not in the rules gets dropped
This is not validator pedantry, it is protection: the form accepts only declared fields, otherwise anything at all could be slipped into it — sudo or active, for example. So every new field has to be declared, even if there is nothing to check in it ('nullable|string').
If the field has a database column
phone is a column of the modx_user_attributes table, MODX knows about it. Then two edits are enough, no PHP logic needed.
First edit — declare the field. core/App/config/pbauth.php:
<?php
return [
'rules' => [
'register' => [
'phone' => 'required|string|unique:user_attributes',
],
],
];Read it like this: the phone is required, it is a string, and no such phone exists yet in the user_attributes table.
Second edit — add the field to the form. In core/App/elements/auth/chunks/form.register.tpl, following the pattern of its neighbours:
<div class="form-group mb-3">
<label class="mb-2" for="phone">Phone</label>
<input type="text" name="phone" id="phone"
class="form-control{if $errors.phone} is-invalid{/if}"
value="{$old_input.phone|escape}" required>
<span class="invalid-feedback" data-error="phone">{$errors.phone|escape}</span>
</div>That's all. The phone saves itself.
|escape on every print of a value
$old_input is what the visitor submitted, and Fenom does not escape on its own. A field added without the modifier is a new hole in a form the component has just had fixed — see Escaped output and the 1.1.1 upgrade.
The phone then works as a login too
Login looks a person up by login, by email and by phone. Phones are stored in the database as digits only, but people type them however they like — with a plus sign, spaces, brackets — so the comparison is normalised against normalised. Short input (fewer than seven digits) is not searched by phone at all: among the legacy rows there are fragments like 998, and they would have matched somebody else's profile.
If there is no database column
telegram, for example. MODX keeps such fields in the service field extended — you have to put them there yourself. The first two edits are the same, a third one is added.
Third edit — a small class that distributes the fields.
core/App/Events/Auth/StoreExtendedFields.php:
<?php
namespace PageBlocks\App\Events\Auth;
class StoreExtendedFields
{
protected const FIELDS = ['telegram', 'viber'];
public function handle(array $params, string $event): void
{
$profile = $params['profile'] ?? null;
$validated = $params['validated'] ?? [];
if (!$profile) {
return;
}
$extended = $profile->get('extended') ?: [];
foreach (static::FIELDS as $field) {
if (array_key_exists($field, $validated)) {
$extended[$field] = $validated[$field] ?? '';
}
}
$profile->set('extended', $extended);
}
}And tell the component when to call it — before the user is saved:
<?php
use Boshnik\PbAuth\Events\Dispatcher;
use PageBlocks\App\Events\Auth\StoreExtendedFields;
return [
'rules' => [
'register' => ['telegram' => 'nullable|string'],
'profile' => ['telegram' => 'nullable|string'],
],
'listeners' => [
Dispatcher::USER_SAVING => [StoreExtendedFields::class],
],
];There is no need to save the profile inside the class — the component saves it immediately afterwards.
USER_SAVING fires both on registration and on a profile edit
If the field is only needed in one of the two cases, look at $params['action'] — it holds either register or profile.
Removing a shipped field
Set it to null and take it out of the form chunk:
'rules' => [
'profile' => ['fullname' => null],
],null removes the field outright, it does not make it optional. It was done this way so that one extra field would not force you to rewrite the whole rule set.
Common validation rules
| Rule | What it means |
|---|---|
required | required |
nullable | may be left empty |
string, integer | value type |
email | looks like an email address |
min:8, max:30 | length |
boolean | a flag: 1/0, true/false, "on" |
alpha_dash:ascii | Latin letters, digits, a hyphen and an underscore, nothing else |
regex:… | matches the pattern. Written without delimiters, see below |
confirmed | a field name_confirmation with the same value must be next to it |
unique:users | no such value exists yet in the modx_users table |
exists:user_attributes,email | such a value does exist in the table |
empty | the field must arrive empty (a honeypot) |
exclude | check it, but do not carry it through to saving |
file, image, mimes:jpg,png, max:2048 | an uploaded file |
Rules are written with |: 'required|string|min:3|max:30'.
string is mandatory for numeric logins
Without it min and max compare the magnitude, not the length, and the login 2385672156 passes max:30 as a number of two billion and change. That is why the shipped registration rule is required|string|alpha_dash:ascii|min:3|max:30|unique:users.
unique: and exists: take a table name, not a MODX class
unique:users, unique:user_attributes — yes. unique:modUser — no: the check silently finds nothing and lets the duplicate through.
The profile username rule
The two shipped rules for the same field are deliberately different:
// registration — a whitelist
'username' => 'required|string|alpha_dash:ascii|min:3|max:30|unique:users',
// profile — a ban on five characters (since 1.1.1)
'username' => 'required|regex:^[^<>"\'&]+$|unique:users,username,:user_id',Up to 1.1.1 the profile rule was just required|unique, and that asymmetry was a hole: you could not register as <img src=x onerror=…>, but you could rename yourself to it, after which the name went into the page.
Why the profile does not get the whitelist too
The profile rule also applies to names that were not created through pbAuth at all: entered by an administrator in the MODX manager, carried over from another system, or taken from a social network — SocialController puts the provider's nickname into the profile. alpha_dash:ascii would stop the owners of such names from saving their profile at all, and a Cyrillic name on a Russian site is perfectly ordinary. Checked: Cyrillic, Japanese, dots, hyphens and underscores all pass.
What it costs: the apostrophe goes with the markup characters
O'Brien and Ім'я cannot be a username. For username that is acceptable — it is typed in Latin without punctuation — but it would not do for fullname, and there the ban is deliberately absent: that field holds a person's real name.
Login has no such rule either, also deliberately. There a person would get a validation refusal instead of "wrong password", and the owner of a name already stored with a markup character would not be able to sign in at all — including to fix the name.
A regex: pattern must contain no |, : or ,
A rule string is parsed by explode('|'), then explode(':', 2), then explode(','). Any of those three characters inside the pattern tears the rule into pieces. In the rule above a stray comma would be handed to unique as an extra argument, and unique would stop excluding the row itself — the person could no longer save their profile without changing their name.
The pattern also carries no delimiters and no flags: ^[^<>"\'&]+$, not /^…$/u.
The refusal text comes from the auth.username_forbidden_chars label. If your core/App/lang/*/auth.php is an edited file, that key is not in it and the visitor sees the key itself — why, and what to add.
What honeypot is for
The login, registration and password recovery forms have a honeypot field with the empty rule: a person does not see it and does not fill it in, a bot does. On every form except login it also has exclude — it needs checking, and after that it is not needed.
If you are building a form from scratch, keep this field in the markup. And do not rename it without fixing the rules.
Avatar
Two fields in the profile are already declared, and both are exclude — they are checked, and nothing is carried through to saving under those names:
'delete_photo' => 'nullable|boolean|exclude',
'newphoto' => 'nullable|file|image|mimes:jpg,jpeg,png|max:2048|exclude',Where to put the files is a setting, :user_id is substituted:
'avatar_path' => 'assets/images/avatars/:user_id',The path is stored in the profile's photo. To raise the size limit, edit max:2048 (kilobytes) — and remember that above it the ceiling is still set by upload_max_filesize and post_max_size in PHP.
photo has no rule, and that is not an oversight
Since 1.1.1 the form sends an intent, not a path. The hidden field is delete_photo, and the "Delete photo" button raises the flag instead of clearing a path:
<input type="hidden" name="delete_photo" value="">The value of photo is set by the controller and only by it — from store() when a file arrives, or to an empty string when the flag is up. The third case, "do not touch the avatar", comes for free: photo has no rule, and Validator::validated() builds its result by walking the rules rather than what was submitted, so the key is simply absent and what was saved stays.
Do not declare photo in your own rules
That is exactly what the hole was: with 'photo' => 'nullable|string' the avatar path could be submitted, and fromArray() wrote whatever string it was given into the profile. On a site with a forum the picture then shows up next to other people's posts. If you had edited form.profile.tpl and it still sends name="photo", see the upgrade page.
For listeners: photo is now in $validated only when it changed. See Events.
If a field is not being saved
Two questions, in order:
- Is it declared in
rules? Everything that is not there is discarded before saving. - Does it have a database column? If not — you need a class on
USER_SAVING, see above. A field that is declared but "does not exist" passes validation and quietly disappears: MODX does not know where to write it.