Download the PHP package ramondev/formcraft without Composer

Formcraft — Complete Usage Guide

Formcraft is a declarative form library for Laravel. You declare a form's fields once as a PHP class, and Formcraft handles HTML rendering, server-side validation, theming (Bootstrap/Tailwind/your own), file uploads, model binding, repeated field groups, and multi-step wizards.

This guide covers everything needed to use the package day to day: install, build forms, render them, validate and save data, upload files, theme them, and wire up wizards — based on the actual package source (ramondev/formcraft).

Table of contents

1. Installation
2. Quick start
3. Defining fields
4. Field option reference
5. Rendering a form
6. Validating a submission
7. Reading submitted values
8. Saving to an Eloquent model
9. File & image uploads
10. Group fields (nested/repeated data)
11. Form Sets ("add another" repeated forms)
12. Multi-step wizards (FormWizard)
13. Theming
14. Customizing a form at runtime
15. Artisan commands
16. Full worked example
17. Behavior notes & gotchas

1. Installation

Install Formcraft straight from Composer:

FormServiceProvider registers automatically via Laravel package auto-discovery — no manual config/app.php edit needed. After installing, php artisan list should show make:form and make:theme.

To update to a newer version later:

Requirements: PHP ^8.1, Laravel (illuminate/*) ^10–^13, and intervention/image ^4.2 (used for resizing image uploads).

2. Quick start

Every form is a class extending Formcraft\FormProcessor that implements setFields():

In a controller:

In a Blade view, just echo the form — every field renders itself:

You can also scaffold a new form with Artisan (see §15):

3. Defining fields

setFields() must return a LaravelFormTemplate, built from a closure that receives a FormFields builder and returns an associative array of field_name => $f->SomeField(...). The array key is the field's name (used for the HTML name/id, the validation key, and the model attribute on save).

Available field builders

4. Field option reference

Every builder above shares this common set of keyword arguments (pass only the ones you need — all have sensible defaults):

Type-specific options

DateField

• format — appended as a second Laravel date rule parameter.

PasswordField

• hashValue (bool, default true) — when saving via save(), the value is run through Hash::make() before being written to the model.

IntegerField

• min, max — numeric bounds (validation + HTML attrs).
• step — HTML step attribute.

SelectField

• options — array of either plain scalars (['a', 'b']) or associative arrays: ['value' => ..., 'text' => ..., 'attr' => [...], 'selected' => bool]. value can itself be a two-element array [storedValue, displayLabelWhenResolved] if you want the raw HTML value to differ from what values() returns.
• multiple (bool) — renders a multi-select and expects/returns an array.

FileField

• multiple (bool) — allow multiple files.
• accepts (array) — HTML accept list (e.g. ['.pdf', '.docx']).
• fileMimes (array) — adds a Laravel mimes: validation rule.
• min / max — min/max validation for each file's size, in kilobytes (Laravel's file-size rule). With multiple: true this still applies per file, not to how many files were uploaded.
• minFiles / maxFiles — only meaningful with multiple: true; validates the number of files uploaded (Laravel's array rule combined with min:/max:), separate from min/max above.
• uploadTo (string, default 'upload') — destination directory.
• imageSize (string, e.g. "800x800") — resize dimensions (images only).
• thumbnail (string, e.g. "150x150") — also generate a thumbnail (images only).
• oldFile (string) — a previously-stored filename to delete once the new upload succeeds.
• fileType (string, default 'file') — adds a matching validation rule (ImageField sets this to 'image' automatically).
• filename (string) — save the upload under this name instead of an auto-generated one (the original extension is appended automatically if you don't include it).
• thumbnailTo (string) — destination directory for the thumbnail; defaults to uploadTo when omitted, so the thumbnail can live in its own folder.
• thumbnailName (string) — save the thumbnail under this name instead of the default "thumb_" + filename.
• oldThumbnail (string) — a previously-stored thumbnail filename to delete (from thumbnailTo) once the new upload succeeds — the thumbnail equivalent of oldFile.
• thumbnailSaveAs (string) — model attribute the thumbnail's filename is written to on save(), alongside the main file's saveAs (see below).

ImageField

• Same as FileField, but type/fileType are pre-set to image handling, and accepts/fileMimes default to common image extensions (jpg, jpeg, png, gif, webp, bmp) unless you pass your own accepts.

Example — a multi-photo upload capped at 4 files, 2 required minimum, each up to 2MB, with a friendly attribute name in every validation message:

The [] suffix on the field key is what tells the browser to submit multiple files under the same name; internally Formcraft strips it, so $form->values()->photo and error messages both refer to the field as photo, not photo[].

Want each photo named individually instead of one shared name (so a message reads "Photo 2 must be an image" rather than "Photos must be an image")? Pass a callable instead of a string — it's called once per submitted file with that file's index:

This turns the default photo.0 / photo.1 / ... keys Laravel would otherwise show into Photo 1 / Photo 2 / ... in every message for that item. It works the same way on an array-typed GroupField's own validateMessageAttribute (naming each row, e.g. "Row 1", "Row 2").

GroupField

• fields (array) — child fields, built the same way as top-level setFields().
• valueType (string, default "all") —
  • "all" — a plain fieldset; children behave like independent top-level fields.
  • "array" — children are named as an array (name[0][city]) and their combined value comes back as an array under the group's own key — use this for repeating nested data.
  • "single" — all children share one input name/value (rare; used for composite single-value widgets).
• applyRuleToFields (array) — extra validation rules applied to every child when valueType is "array" (as "key.*" rules).
• minLength / maxLength (int) — only meaningful when valueType is "array"; validates the number of items in the array (Laravel's min:/max: combined with array), not the length of any single value. Use this for things like "add between 1 and 5 line items".
• validateMessageAttribute (string) — the friendly name used in place of the raw key in validation messages. For valueType: "array" groups this covers both the group's own key ("items") and the per-item wildcard rules from applyRuleToFields ("items.*"). To rename an individual child field's key in messages (e.g. "items.name" → "Item name"), set validateMessageAttribute on that child field itself, the normal way ($f->CharField(validateMessageAttribute: 'Item name')) — it's picked up automatically, including for nested groups.
• groundName — internal; lets nested groups compute dotted array names correctly.

5. Rendering a form

Whole form at once — a FormProcessor instance has a __toString(), so you can just echo/print it (e.g. {!! $form !!} in Blade). Each field is wrapped and rendered according to the active theme.

One field at a time — access any field as a property to get a compiled object with ->label, ->input, and ->errors:

Each of ->label, ->input also has its own __toString(), so you can echo them directly ({!! $form->email->input !!}), or read finer detail off them: $form->email->input->name, ->id, ->value, ->is_required, etc.

6. Validating a submission

• validate(array $data, array $files = []) — stages the submitted data (and optionally files) for validation; doesn't run anything yet.
• is_validated(): bool — runs every field's Laravel validation rules (built automatically from the field options in §4, plus any validateRule you added) and returns whether all fields passed.
• errors(): ObjectClass — after is_validated() returns false, use:
  • $form->errors()->all() — flat array of "field" => "combined message".
  • $form->errors()->messages() — "field" => [message, message, ...].
  • $form->errors()->get(['field']) — messages for one specific field.
  • $form->errors()->first() / ->last() — first/last error message overall.

If you render the form again after a failed submission (without redirecting), fields marked cache: true (the default, except PasswordField) automatically repopulate from Laravel's old() input.

7. Reading submitted values

values() resolves each field's submitted value — including matching a SelectField's stored option back to its declared value, and substituting uploaded files with their generated filenames once uploadFiles() has run.

Detecting changes against an initial value (e.g. an edit form pre-filled via initialValue()):

8. Saving to an Eloquent model

save() copies every fillable field's resolved value onto the bound model (calling ->save() on it at the end). Control exactly what gets copied:

• setFillableAttribute(array $keys) — only copy these field keys (default: every key present in the submitted data).
• setExceptAttribute(array $keys) / addToExceptAttribute(array $keys) — exclude specific keys from being copied.
• changeSaveKey(['formField' => 'model_attribute']) — write a field's value to a different model attribute name (overrides a field's own saveAs option for this instance).
• A field's own saveAs: 'profile.bio' option (see §4) writes into an already-loaded relation instead of a literal attribute — if any segment of the path isn't already set on the model, that assignment is silently skipped rather than erroring.
• setDefaultAttributeValue(['created_by' => $userId]) — attributes applied to the model before the field values are copied over, useful for values that don't come from the form itself.

setModelAttribute() performs the copy without calling ->save(), if you need to do more to the model first.

Passwords: a PasswordField with hashValue: true (the default) is automatically run through Hash::make() when copied onto the model.

9. File & image uploads

Basic upload

Declare the field:

Then, in your controller, explicitly trigger the upload (this is a separate step from validation/save, so you control exactly when files hit disk):

• uploadFiles(bool $returnWithPath = false) — uploads every file field. By default only the generated filename is stored; pass true to store the full "path/filename" instead.
• getUploadedFiles(): ObjectClass — inspect what was uploaded, keyed by field name (nested by group, for group fields).
• Non-image files are moved as-is; image files are opened and optionally resized to imageSize.
• Passing oldFile (the previous filename) deletes that old file once the new upload succeeds.

Custom filenames

By default an uploaded file gets an auto-generated unique name. Set filename to force your own instead — the original extension is appended automatically if you don't include one:

Thumbnails: separate folder, own filename, deletable, saved to the DB

Add thumbnail (the resize dimensions) to have a thumbnail generated alongside the main upload. Four more options give you full control over it:

With thumbnail set, the field's resolved value is no longer a plain filename string — it becomes ['filename' => ..., 'thumbnail' => ...], so:

thumbnailSaveAs makes save() write both filenames onto the model in one call — the main filename to the field's usual saveAs, and the thumbnail's filename to whatever attribute thumbnailSaveAs names:

If a field has thumbnail set but no thumbnailSaveAs, only the main filename is written on save — the thumbnail filename is still available via values()/getUploadedFiles() if you want to handle it yourself.

Using FileManager directly

Under the hood, uploads go through Formcraft\FileManager, which you can also use standalone (e.g. outside of a form, for an ad-hoc upload):

Every FileManager method can also be called statically, e.g. FileManager::removeFile('uploads/avatars/old.jpg').

10. Group fields (nested/repeated data)

Use GroupField to nest several fields under one key.

Plain grouping (valueType: "all", the default) — just visual/logical grouping; children behave like normal top-level fields:

Repeated/array data (valueType: "array") — for something like "add up to N line items", where the submitted HTML uses array-style names (items[0][name], items[1][name], ...) and the group's resolved value is an array of child arrays:

Here, minLength/maxLength cap the number of rows (1 to 5 items), and validateMessageAttribute renames "items"/"items.*" to "Line items" in error messages, while the name field's own validateMessageAttribute renames just "items.name" to "Item name".

Validation rules for array-typed groups are generated per index automatically (items.*.name, items.*.qty), and values()/save() flatten group children's values into the top-level result, so $form->values()->items gives you the full array of rows.

Groups can be nested inside groups; access a nested field's props at definition time via a "parent/child" path with changeProps() (see §14).

11. Form Sets ("add another" repeated forms)

FormSet builds several independent copies of a whole FormProcessor class — useful when each "row" needs its own full validation/theme rather than being one group of fields.

Key FormSet methods:

Redisplaying errors after a failed submission

A FormSet you build to render the page (e.g. in your create() action) is a fresh set of FormProcessor instances — it has no memory of a previous failed validate() call, even one from the very same request cycle a moment ago. If you return back()->withErrors(...)->withInput() after validation fails and then redisplay the page, its errors won't show up unless you explicitly re-validate the new instances from the flashed old() input:

This mirrors what FormWizard::form() already does internally for a single step. If your view tracks a dynamic row count (an "add row" button), also flash/read that count (e.g. a hidden item_count input) so the redisplay rebuilds the same number of rows the person actually submitted.

12. Multi-step wizards (FormWizard)

FormWizard drives a sequence of FormProcessor "steps" — one submitted and validated at a time, stored in the session, with everything available once all steps are complete.

Other methods: stepKeys(), completedSteps(), goToStep($step) (jump back, un-completing that step and everything after it — stored data is kept so it still pre-fills), and reset() (clear all progress).

13. Theming

A theme controls the CSS classes injected into labels/inputs and how a field's label/input/errors are wrapped together — without you touching your field definitions.

Built-in themes

Applying a theme

Per instance:

As a form's standing default, override defaultTheme() in your FormProcessor subclass:

A field's own widget option (§4) always wins over the theme for that one field — it bypasses theming entirely.

Writing your own theme

Implement Formcraft\Support\FormTheme (or run php artisan make:theme YourName — see §15):

14. Customizing a form at runtime

These let you tweak an already-defined form on a per-instance basis, without touching setFields():

15. Artisan commands

make:form — scaffold a new form class

make:theme — scaffold a new theme class

Generates a class implementing FormTheme with all three required methods stubbed out and commented, under app/{--path} (default app/Themes).

16. Full worked example

Form definition (app/Forms/RegistrationForm.php):

Controller:

Blade view (resources/views/register.blade.php):

That's it — Formcraft renders every field with Bootstrap classes, validates on submit, uploads and resizes the avatar, hashes the password, and saves the new User.

17. Behavior notes & gotchas

A few implementation details worth knowing as you use the package:

• values() vs raw $request input: always read submitted data through $form->values(), not the raw request — it resolves SelectField option matching and substitutes uploaded files' final filenames once uploadFiles() has run.
• Upload order matters: call uploadFiles() after is_validated() passes and before save() (or before reading values() for a file field), so the resolved value is the new filename rather than the raw uploaded file object.
• PasswordField isn't cached by default (cache: false) — on a failed submission the password field is intentionally left blank rather than repopulated from old().
• removeFile()/thumbnail cleanup: deleting the old main file and the old thumbnail are two explicit, independent operations — oldFile (from uploadTo) and oldThumbnail (from thumbnailTo). Set both when you want both cleaned up; FileManager::removeFile() never guesses a thumbnail's path from the main file's.
• File field values change shape once a thumbnail is configured: a FileField/ImageField without thumbnail resolves to a plain filename string, same as always. Add thumbnail and it resolves to ['filename' => ..., 'thumbnail' => ...] instead (from values() and getUploadedFiles()) — code that reads that field's value as a plain string needs updating if you add a thumbnail to an existing field.
• DateField's extra validateRule: a validateRule array you pass to DateField is appended as one nested array element alongside the automatic date (and optional format) rules, rather than merged flat into the rule list — pass any extra Laravel date-related rule as a single array item if you rely on this option.
• Group field naming: for valueType: "array" groups, HTML input names use bracket syntax (items[0][name]), while Laravel validation and values()/save() use dot syntax (items.0.name) — you don't need to convert between them yourself, but keep it in mind if you're inspecting raw request data.
• ignore: true fields are skipped everywhere: they don't render, validate, appear in values(), or get written on save().