alveby / atrium-forms
Forms and submissions for Atrium: a form builder in the admin, a Blade component for the site, mail, anti-spam
Requires
- php: ^8.3
- alveby/atrium: ^0.1
- illuminate/support: ^13.0
Requires (Dev)
- orchestra/testbench: ^11.0
- phpunit/phpunit: ^12.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 19:17:38 UTC
README
Forms and submissions for Atrium: an editor builds a form in the admin, the site shows it with one Blade tag, and what visitors send is kept in the admin and mailed to the addresses set on the form. Spam is stopped without an outside service.
Install
composer require alveby/atrium-forms php artisan atrium:module:install alveby/atrium-forms
atrium:module:install creates the tables and turns the module on; atrium:module:remove alveby/atrium-forms turns it off and asks whether to keep the forms and submissions.
The admin gets three entries:
| Entry | What it holds |
|---|---|
| Forms | name, code, the addresses submissions are mailed to, the button text and the message after sending (both per content language), on/off; the list shows how many submissions each form has |
| Form fields | the form, label (per content language), field code, type, required, options, sort |
| Submissions | what was sent, with the form, page, language, IP address and browser; read and deleted, never edited |
The number of submissions is kept on the form (forms.submissions_count): it goes up when a submission is stored and down when one is deleted in the admin, so the list does not count them on every page.
Forms belong to sites: each site has its own, and the lists show the current site's forms, fields and submissions. Each entry has the usual four permissions in the role form; give an editor form_submissions.view to read the submissions.
Field types: text, e-mail, phone, number, date, long text, list, radio buttons, checkbox. A list and radio buttons take their options one per line, in each language. The rules follow the type: a valid e-mail, a phone of digits and +()-., one of the options, a required checkbox must be ticked.
On a page
<x-atrium-forms::form code="contact" />
draws the form of the current site with that code, in the page's language, or nothing when there is none or it is off. Attributes pass to the <form> tag (class is added to atrium-form). The form posts to /forms/{code} (/de/forms/{code} in another language) and comes back to the same page, scrolled to the form, with the message or the errors; several forms on one page keep their own errors and input. A request that wants JSON gets {"message": "…"} or the usual 422 with errors.
The markup is plain HTML with atrium-form* classes and a few styles that take the colours of alveby/atrium-theme. To change it, php artisan vendor:publish --tag=atrium-forms-views.
Spam and limits
- A hidden field people never see and bots fill in. A submission with it filled is answered as sent and dropped.
- The time the form was drawn, encrypted with the app key. A form sent sooner than
min_seconds(3) after that, or without the time, is refused with "sent too quickly". - At most
per_minute(5) submissions of one form from one IP address per minute. - The site's captcha, when one is on (
ATRIUM_CAPTCHA:imagebuilt in,recaptchafor Google reCAPTCHA v2,noneby default): every form asks it under its fields.captcha => falseinconfig/atrium-forms.phpkeeps it off the forms.
php artisan vendor:publish --tag=atrium-forms-config copies config/atrium-forms.php to change these, the honeypot field name, the captcha and the address prefix; ATRIUM_FORMS_MIN_SECONDS and ATRIUM_FORMS_PER_MINUTE work without it.
Each submission goes to every address of its form through Laravel's mail (MAIL_* in .env, the same that sends the admin's sign-in codes). "Reply" answers the visitor when the form has an e-mail field. A form without addresses only keeps submissions in the admin. A mail server that is down does not lose a submission: it is stored first, and the error goes to the log.
To do more with a submission (a CRM, a chat), listen to the model's event:
use Atrium\Forms\Models\FormSubmission; FormSubmission::created(function (FormSubmission $submission) { // $submission->form_name, $submission->data: [['name' => 'email', 'type' => 'email', 'label' => 'E-mail', 'value' => '…'], …] });
The labels are kept in the site's default language as they were when the form was sent, so a submission reads the same after the form changes or is deleted.
Languages
The admin's 15 languages. English and Russian are written by hand, the rest are machine translations awaiting native review.
Tests
From the repository root:
vendor/bin/phpunit packages/forms/tests
Contributing
This repository is a read-only copy of packages/forms in AlveBy/atrium. Issues and pull requests go there.
License
MIT