Admin state changes: POST, token, confirm
An admin action of yf that changes something (deletes, purges, rebuilds, sends, saves) runs only from a POST that carries the
session CSRF token, sent by a button that can ask for a confirm first. A link (GET) to such an action never changes
anything: it shows a confirm page that sends the same URL again by POST. One helper does all of it for every admin module:
_class('admin_post') (class yf_admin_post, plugin sys). It checks the token whether or not the
dispatcher's CSRF guard is turned on for the admin, so a module is safe on every site.
The button
$html = _class('admin_post')->post_form('./?object=my_module&action=wipe', ['id' => $id], t('Wipe'), [
'confirm' => t('Wipe this entry now?'), // a JavaScript confirm before sending ('' none)
'type' => 'danger', // default, primary, danger...: Bootstrap 3 or 5 classes
'icon' => 'fa fa-trash',
]);
The form holds the token field (token_input()) and one hidden field per entry of the second argument (an array value
becomes name[] fields, a deeper array one field with its JSON). The label, the URL, the field values, the confirm text and the title are escaped, template braces
included; pass 'html' => true for a label that is already HTML. Other options: size (xs or sm under
Bootstrap 3), btn_class (the whole button class), class and style of the form, title,
attrs / form_attrs (more attributes, escaped), extra_html (controls before the button) and
'js' => false when the page has its own script for form[data-confirm].
The action
public function wipe()
{
if (($refused = _class('admin_post')->refusal('my_module', 'wipe')) !== null) {
return $refused;
}
// ... the change, then a redirect
}
refusal() returns null when the action may run: the console, or a POST with the token (POST field
_token or the X-CSRF-Token header, compared with hash_equals()). Otherwise it returns what to
show:
- a GET from a browser: the confirm page (
confirm_form(), templatesystem/confirm_action, the same look under Bootstrap 3 and 5) that sends the URL by POST, and Cancel; - a GET from htmx (not a boosted link): the confirm form as a fragment (below);
- a GET from a script (ajax,
X-Requested-With): HTTP 403 and a short text, since a script cannot click a confirm button; - a POST without a valid token: HTTP 403, "Invalid CSRF token", and a row in the CSRF log.
core_blocks::post_only_refusal() decides first, so a site that overrides it still decides for every module.
htmx
An element with hx-get that points at such an action gets the confirm form in its target (it needs an id);
Confirm sends the same URL with hx-post and the token, and a redirect of the module then loads the page
(HX-Redirect). An htmx POST without the token gets the 403 without a swap and a toast. The flow, its headers and a live
example: htmx / Admin confirm over htmx.
A module that keeps an old GET link behind a switch (for example CSRF_PROTECT, off until 4.0) passes
['enabled' => $this->CSRF_PROTECT].
Only the check
csrf_ok('my_module.wipe') is true when the request carries the token; a refusal is logged under that
name (no name: not logged). guard_csrf_ok() takes the same arguments and asks
_class('admin_fs_guard')->csrf_ok(), the older entry point a site may override; the framework modules that called it
before still do. Its second and third arguments stand in for $_POST and $_SERVER, for a decoded JSON
body or a test. A script sends the token in the X-CSRF-Token header; the admin's own scripts already do.
Sites
Modules keep their own small methods (_csrf_ok(), _token_input(), _post_form()...) as thin
wrappers of the helper, so a site class that overrides one of them keeps working. A site changes the look or the rules for all modules
at once with its own admin_post class extending yf_admin_post.