Version 9

[aerni]

This PR features a major refactor of the codebase with many improvements and new features. There are some breaking changes that require your attention when upgrading.

What's new

• Rewritten from the ground up for Livewire 3.
• Support for Statamic 5.
• Support for Laravel 11.
• New wizard form type.
• Major performance improvements.
• Conditional fields powered by Alpine, resulting in a much snappier user experience.
• More powerful field models by leveraging a custom FieldSynth synthesizer
• FilePond integration for the Assets field.
• Prettier commands thanks to Laravel Prompts.

Breaking changes

• Complete overhaul of the theme folder structure and its views.
• Replaced the @formSections, @formHoneypot, @formSubmit, @formErrors and @formSuccess blade directives with a global @formView directive.
• Removed the hydratedFields, submittingForm, createdSubmission, and submittedForm hooks.
• Removed the submissionCreated event.
• Removed the $HANDLE, $VIEW and $THEME component properties.
• Removed showLabel field property.

Upgrade Guide

This upgrade guide takes you through the breaking changes of this PR. If you made major customizations to the underlying Livewire form component, you might run into more breaking changes, as this PR features a complete rewrite of the codebase. Feel free to reach out if you encounter any breaking changes that are not listed below.

Themes and views

The theme directory and views have been restructured and optimized. The changes include Alpine for field conditions and general improvements of field views. I recommend you publish a temporary migration theme and view using the setup command, and adapt your existing views accordingly.

php please livewire-forms:setup

Renamed views

• The checkbox.blade.php view has been renamed to checkboxes.blade.php
• The input.blade.php view has been renamed to default.blade.php
• The file.blade.php view has been renamed to assets.blade.php

Blade directives

The @formSections, @formHoneypot, @formSubmit, @formErrors and @formSuccess blade directives have been removed in favor of a new @formView blade directive.

- @formHoneypot
+ @formView('fields.honeypot')

- @formSubmit
+ @formView('buttons.submit')

- @formErrors
+ @formView('messages.errors')

- @formSuccess
+ @formView('messages.success')

label property

The label property has been renamed to display for consistency with Statamic's naming scheme. You should update your views accordingly.

- {{ $field->label }}
+ {{ $field->display }}

showLabel property

The showLabel property has been removed. This change is reflected in the updated views.

Form components

If you've got a custom form component, you should apply the following changes.

Extending component

The component namespace has changed. Update accordingly:

- use Aerni\LivewireForms\Http\Livewire\BaseForm;
+ use Aerni\LivewireForms\Livewire\BaseForm;

Component properties

The static component properties $HANDLE, $VIEW, and $THEME have been removed. You should mount the public properties instead:

- protected static $HANDLE = 'contact';
- protected static $VIEW = 'secondary';
- protected static $THEME = 'secondary';

+ public function mount(): void
+ {
+     $this->handle = 'contact';
+     $this->view = 'secondary';
+     $this->theme = 'secondary';
+ }

Hooks

hydratedFields

The hydratedFields hook has been removed. There are a couple of alternatives you can use instead.

mountedFields

The mountedFields hook is called when the component is mounted. It is more efficient from a performance point of view as it is only called once. This hook is what you should be using most of the time.

- protected function hydratedFields(Fields $fields): void
+ public function mountedFields(Collection $fields): void
{
    $fields->get('name')->label('Your name');
}

hydrateFields

The hydrateFields hook works similar to the deprecated hydratedFields hook. It is called every time the component is hydrated. This hook allows for dynamic updates to your fields on every request, at the expense of performance.

- protected function hydratedFields(Fields $fields): void
+ public function hydrateFields(Collection $fields): void
{
    $fields->get('name')->label('Your name');
}

submittingForm, createdSubmission, submittedForm

The submittingForm, createdSubmission, and submittedForm hook have been removed. Use the formSubmitted hook instead.

- protected function submittingForm(): void
+ public function formSubmitted(Submission $submission): void
{
-    $this->data['created_at'] = now()->timestamp;
+    $submission->set('created_at', now()->timestamp);
}

Events

The submissionCreated Livewire event has been removed. You should listen for the form-submitted event instead.

Field models

Field models have been substantially refactored. Each field now holds and processes its own value when the form is submitted.

$fields public property

Previously, we used the public $data property for storing the data of a form. This property has been removed in favor of the $fields property. This property contains all the field model classes with their properties and values.

This change affects validation and custom messages. So you should update accordingly:

Validation in your form blueprints

validate:
-  - 'required_if:data.newsletter,true'
+  - 'required_if:fields.newsletter.value,true' 

Messages in your custom form components

protected $messages = [
-    'data.text_field.required' => 'What is your name darling?',
+    'fields.text_field.value.required' => 'What is your name darling?',
];

Renamed model

You should update the checkboxes field model binding in config/livewire-forms.php:

- \Statamic\Fieldtypes\Checkboxes::class => \Aerni\LivewireForms\Fields\Checkbox::class,
+ \Statamic\Fieldtypes\Checkboxes::class => \Aerni\LivewireForms\Fields\Checkboxes::class,

label property

The label property has been renamed to display. If you are programmatically setting this property, you should update your code accordingly.

- $field->label('Custom');
+ $field->display('Custom');

showLabel property

The showLabel property has been removed. If your project relies on it, you may always add it back yourself.

Property methods

If you are setting a field property in a form component or view, the value is now passed through and processed by the respective property method. If you've got your own models with custom property methods, you should update those methods to accept a value so it can be processed:

- protected function autocompleteProperty(): string
+ protected function autocompleteProperty(?string $autocomplete = null): ?string
{
-    return $this->field->get('autocomplete', 'on');
+    return $autocomplete ?? $this->field->get('autocomplete');
}

If a property method doesn't accept an argument, the property will be considered read-only.

[ceesvanegmond]

@aerni What is the status on this? The latest tagged release is 8.1.0 which isn't compatible with LiveWire 3 yet.

[aerni]

I'm working on the finishing touches. This version is a complete refactor. The biggest work now is the upgrade guide.

[ceesvanegmond]

@aerni Nice! Can I already test it out? When do you expect to tag 3.0?

[aerni]

Sure, you can check out this branch to take it for a spin. You'll run into more or less breaking changes depending on your setup. I don't have an ETA.

[aerni]

@ceesvanegmond I'm almost ready to tag a release. Are you planning to update any time soon? If yes, are you willing to test drive this PR before I tag a release? I added an upgrade guide at the top that should contain all the major road blocks.

[ceesvanegmond]

@aerni I updated our application to latest dev-main en everything seem to be allright! Very Nice!

[aerni]

@ceesvanegmond The main branch is behind a lot and doesn't cover any of the breaking changes. You should check out major-refactor instead.

[martinsnajdr]

Hello, do you plan to support Statamic V5 in this release?

[aerni]

Yes, that's the plan! 😄