Upgrade guide: v6 to v7

Laravolt v7 is a minor-to-major jump in the underlying stack. Most application code keeps working, but some packages, method names, and UI classes changed. This guide lists the concrete differences and the recommended upgrade order.

Dependency matrix

Breaking changes at a glance

1. Form facade renamed. Form:: → PrelineForm::. The helper form() still exists and now returns the PrelineForm builder. See Forms overview.
2. Default UI is Preline UI + Tailwind CSS. Fomantic/Semantic UI classes are deprecated. Custom classes added to fields must be migrated to Tailwind equivalents.
3. Laravel components remain compatible with ^11|^12|^13. Test your application against the exact Laravel version you deploy.
4. Livewire 4. Livewire 3 components may need minor adjustments; see the Livewire 4 upgrade notes.
5. PHPUnit/Pest. Tests are expected to run under Pest 4. Plain PHPUnit tests still work.
6. Client-side validation hook added. Forms using ->validate() now emit HTML validation attributes and data-validation-rules automatically. Existing forms are unaffected unless they relied on the absence of those attributes.

Recommended upgrade order

1. Confirm your Laravel version and follow the Laravel upgrade guide if you are moving framework versions.
2. Upgrade Livewire (3 → 4). Follow the Livewire upgrade notes. Livewire 4 is largely backwards compatible but tightened some lifecycle behaviour.
3. Upgrade PHP to 8.2+ if you are not already there.
4. Run composer require laravolt/laravolt:^7.0.
5. Run composer require laravolt/preline-form (if not already installed). Consider removing laravolt/semantic-form once the migration is complete.
6. Run php artisan laravolt:install to re-publish configuration and assets. Review the diff before committing.
7. Run php artisan migrate.
8. Run your full test suite.

Migrating forms

The form API is intentionally compatible, but a search-and-replace is the fastest way to move:

- use Laravolt\SemanticForm\Facade as Form;
+ use Laravolt\PrelineForm\Facade as PrelineForm;
- {!! Form::open('users.store')->post() !!}
+ {!! PrelineForm::open('users.store')->post() !!}
- {!! Form::text('name')->label('Name') !!}
+ {!! PrelineForm::text('name')->label('Name') !!}

The form() helper keeps working: form()->text('name') now returns a PrelineForm field.

Deprecated Semantic UI classes

Replace Semantic UI classes added via ->addClass() with Tailwind/Preline equivalents:

If you extended SemanticForm elements, move them to the PrelineForm counterparts:

// v6
class CustomText extends \Laravolt\SemanticForm\Elements\Text { /* ... */ }
// v7
class CustomText extends \Laravolt\PrelineForm\Elements\Text { /* ... */ }

Migrating Blade components

If you used laravolt/ui Blade components in v6, many component names continue to work under v7. Several internal templates moved from Fomantic/Semantic UI to Preline UI, so custom Blade published in your application should be reviewed and re-rendered against Preline UI patterns.

Current v7 views expose <x-volt-*> components such as app layout, buttons, alerts, panels, tables, charts, datepicker, file upload, notification, titlebar, steps, timeline, tree view, and workflow diagram button. Re-render custom published Blade views because internal markup moved to Preline/Tailwind patterns.

Migrating tables, menus, workflows

The public APIs for tables (Suitable), menus, actions, ACL, and Workflow are broadly the same in v7:

• Suitable (tables) — use the Suitable facade/builder or generated table classes from php artisan make:table.
• Menus — register callbacks with app('laravolt.menu.builder')->register(...) or load config arrays under config/laravolt/menu/*.
• Workflow — start processes with WorkflowService::start() and complete tasks with WorkflowService::submitTask().

Migrating tests

Pest 4 tightened a few matchers. If you use Pest:

composer require --dev pestphp/pest:^4.0
vendor/bin/pest --init # if starting fresh

Plain PHPUnit tests continue to work without changes.

Configuration changes

Re-publishing Laravolt configuration may introduce new keys. Review the diff produced by php artisan laravolt:install carefully:

php artisan laravolt:install
git diff config/

Published configuration includes platform/UI/menu files plus package configs such as auto-crud, asset, database-monitor, file-manager, lookup, mailkeeper, media, suitable, thunderclap, and workflow. Review the generated diff after every publish.

Post-upgrade checklist

• [ ] composer install succeeds without conflicts.
• [ ] php artisan migrate runs cleanly.
• [ ] php artisan test (or vendor/bin/pest) is green.
• [ ] Every screen renders with Preline UI styling (no stray Semantic UI classes).
• [ ] Forms submit, validate, and display errors correctly.
• [ ] Input masks initialize after Livewire DOM swaps.
• [ ] Permissions still apply (roles, policies, menu visibility).
• [ ] CI passes on the target PHP version.

Rolling back

If the upgrade goes sideways:

1. Revert the composer lock changes: git checkout HEAD -- composer.json composer.lock && composer install.
2. Roll back configuration changes published by laravolt:install.
3. Restore the previous Livewire/Laravel versions if you bumped them.

Because v7 focuses on package, UI, and integration changes, many applications will not need large data migrations beyond package-published migrations. Verify this with your own migration diff before assuming it holds for your project.

Verify before release

These items should still be rechecked before tagging v7.0.0:

• Packagist package constraints match the repository constraints.
• Starter kit frontend dependencies match the Tailwind/Preline guidance.
• Published config diffs are reviewed on a fresh application.
• Existing apps with published Blade views are manually smoke-tested.

What to read next

• Installation — install v7 into a new or existing Laravel project.
• Forms overview — the new PrelineForm builder, including model binding.
• AI-ready platform — the conventions v7 relies on for safe extension.