Upgrading from v3.x
Follow these steps to upgrade your Craftable PRO installation to v4. This release adds Laravel 13 support and drops Laravel 11.
Most of the work is in your application code: controllers and exports that the Craftable PRO generator wrote for you use the old spatie/laravel-query-builder v6 API, and they have to be updated by hand. The admin's frontend moves to Vite 8 and Tailwind CSS 4.
Estimated effort: 15–60 minutes, depending on how many CRUDs you generated.
Upgrading from v2? Upgrade to v3 first, following the v3 upgrade guide.
New Requirements
- Laravel 12 or 13 (Laravel 11 is no longer supported)
- PHP 8.3+
- Node.js 20.19+ or 22.12 and newer, including 24 and 26 (required by Vite 8)
Upgrade
Check the requirements
| v3.x | v4.0 | |
|---|---|---|
| PHP | ^8.2 | ^8.3 |
| Laravel | 11, 12 | 12, 13 |
| nesbot/carbon | 2 or 3 | 3 |
If you are on Laravel 11, upgrade to Laravel 12 first (Laravel upgrade guide (opens in a new tab)), then continue here.
Update composer dependencies
composer require brackets/craftable-pro:^4.0 -W-W is required, because several dependencies move to a new major version
together:
| Package | v3.x | v4.0 |
|---|---|---|
| spatie/laravel-query-builder | ^6.0 | ^7.0 (breaking, see below) |
| spatie/laravel-permission | ^6.3 | ^8.0 (see below) |
| maatwebsite/excel | ^3.1 | ^3.1.68 or ^4.0 |
| socialiteproviders/apple | ^5.6 | ^5.6 or ^6.0 |
On PHP 8.5 and newer, Composer will install maatwebsite/excel 4.x, because
3.x cannot be installed there.
Update generated controllers and exports (required)
spatie/laravel-query-builder v7 changed allowedFilters(), allowedSorts(),
allowedIncludes(), allowedFields(), defaultSort() and defaultSorts() to
take variadic arguments instead of an array. Passing an array now throws a
TypeError.
Every controller and export that the generator created has this pattern. Find them:
grep -rnE "allowed(Filters|Sorts|Includes|Fields)\(\s*\[|defaultSorts?\(\s*\[" app/…and remove the square brackets:
// Before
$query = QueryBuilder::for(Post::class)
->allowedFilters([
AllowedFilter::custom('search', new FuzzyFilter('id', 'title')),
])
->defaultSort($defaultSort)
->allowedSorts(['id', 'title']);
// After
$query = QueryBuilder::for(Post::class)
->allowedFilters(
AllowedFilter::custom('search', new FuzzyFilter('id', 'title')),
)
->defaultSort($defaultSort)
->allowedSorts('id', 'title');If the list is built at runtime, unpack it: ->allowedSorts(...$columns).
Also check the following, if your code uses them:
'*'wildcards inallowed*()are no longer supported. List the names explicitly.SortDirectionis now an enum:SortDirection::DESCENDING→SortDirection::Descending.AllowedFilter::beginsWithStrict()/endsWithStrict()were renamed tobeginsWith()/endsWith().- Custom delimiters: the static
QueryBuilderRequest::set*Delimiter()methods and the$arrayValueDelimiterargument were removed. Use->delimiter('|')on the filter, or thedelimiterkey inconfig/query-builder.php. - Published
config/query-builder.php:disable_invalid_includes_query_exceptionis nowdisable_invalid_include_query_exception, andcount_suffix/exists_suffixwere merged into a singlesuffixesarray.
Full details: laravel-query-builder UPGRADING.md (opens in a new tab).
Update custom filters and sorts
The Filter and Sort interfaces now declare a void return type, and filters
take mixed $value. Update any custom filter or sort classes in your app:
// Before
public function __invoke(Builder $query, $value, string $property) { /* ... */ return $query; }
// After
public function __invoke(Builder $query, mixed $value, string $property): void { /* ... */ }The same change applies to Craftable PRO's own classes. If you extend them, update your method signatures:
| Class | Change |
|---|---|
Brackets\CraftablePro\Queries\Filters\FuzzyFilter::__invoke() | mixed $values, returns void (previously returned the Builder) |
Brackets\CraftablePro\Queries\Sorts\SortNullsLast::__invoke() | returns void |
Brackets\CraftablePro\Translations\Export\TranslationsExport::collection() | returns Illuminate\Support\Enumerable |
Brackets\CraftablePro\Translations\Import\TranslationsImport::collection() | returns void |
If you called FuzzyFilter directly and used its return value, use the query
you passed in instead. The filter now changes it in place and returns nothing.
Two classes were removed or renamed. Most apps never reference them directly,
because they resolve Brackets\CraftablePro\DatabaseManager\DatabaseManager from the container:
| Before | After |
|---|---|
Brackets\CraftablePro\DatabaseManager\L11DatabaseManager | Brackets\CraftablePro\DatabaseManager\SchemaDatabaseManager |
Brackets\CraftablePro\DatabaseManager\DbalDatabaseManager | removed (Doctrine DBAL is not used since Laravel 11) |
Check spatie/laravel-permission usage (v6 → v8)
The database schema has not changed, so no new migration is needed, and your
published config/permission.php keeps working. The new keys (models.team,
models.default_model, team_resolver) default to safe values.
You only need to act if your app:
- listens to permission events: they were renamed with an
Eventsuffix (RoleAttached→RoleAttachedEvent,PermissionDetached→PermissionDetachedEvent, …); - references the command classes: these also got a
Commandsuffix (CacheReset→CacheResetCommand, …). Artisan command names are unchanged; - extends the
Role/Permissionmodels or implements their contracts:findByName()andfindOrCreate()now acceptBackedEnum|string, andHasRoles/HasPermissionsmethods such asassignRole()andsyncPermissions()now returnstatic; - calls
PermissionRegistrar::clearClassPermissions(): useclearPermissionsCollection()instead.
Full details: laravel-permission upgrading guide (opens in a new tab).
Update frontend dependencies
v4 updates the npm packages the admin is built with, to clear every known
vulnerability (npm audit reports 0). The installer only writes these into new
apps, so update your app's package.json yourself:
| Package | Before | After |
|---|---|---|
vite | ^5.0.0 | ^8.0.0 |
laravel-vite-plugin | ^1.2.0 | ^3.1.0 (3.x requires Vite 8) |
@vitejs/plugin-vue | ^4.0.0 | ^6.0.0 |
@tiptap/* (vue-3, starter-kit, pm, and the image, link, text-align, youtube extensions) | ^2.0.0 | ^3.30.4 |
@tiptap/extension-underline | ^2.0.0 | remove (part of starter-kit since Tiptap 3) |
@tiptap/extension-heading | (none) | add ^3.30.4 |
laravel-vue-i18n | ^1.4.4 | ^2.9.0 (v1 pulls in laravel-mix and webpack) |
uuid | ^9.0.0 | ^14.0.0 |
@types/vue-cropperjs | ^4.1.2 | remove (Vue 2 typings that pull in the vue 2 package) |
Also add this override. @tailwindcss/typography pins a vulnerable
postcss-selector-parser, even in its latest release:
"overrides": {
"postcss-selector-parser": "^6.1.5"
}npm reads overrides. With yarn, add the same entry under resolutions; with
pnpm, under pnpm.overrides. The installer writes all three.
Haven't changed the published frontend files? php artisan craftable-pro:install --overwrite
rewrites craftable-pro.vite.config.js and resources/css/craftable-pro.css for you. Without
--overwrite, the installer keeps your files and warns if they still use Vite 5 or Tailwind 3.
Then reinstall and rebuild:
npm install
npm audit
npm run craftable-pro:buildTwo more changes, if you have published Craftable PRO's frontend stubs:
craftable-pro.vite.config.js: removesplitVendorChunkPluginfrom theviteimport and fromplugins. Current Vite versions no longer have it.- TypeScript only: add
resources/js/craftable-pro/vue-cropperjs.d.tswithdeclare module "vue-cropperjs";, which replaces the removed@types/vue-cropperjs.
If your own code uses Tiptap, laravel-vue-i18n or Vite plugins directly, check
their upgrade guides. The admin's own editor already uses the Tiptap 3 API.
Migrate to Tailwind CSS 4
The admin is now built with Tailwind CSS 4, the version Laravel 12 and 13 apps
ship with. Before, the installer replaced the app's Tailwind 4 with Tailwind 3,
which broke the app's own npm run build.
The admin's theme now lives in the package's CSS, so future theme changes arrive
with composer update. Your app keeps only a small entry stylesheet.
1. Update package.json:
| Package | Before | After |
|---|---|---|
tailwindcss | ^3.x | ^4.0.0 |
@tailwindcss/vite | (none) | add ^4.0.0 |
@tailwindcss/forms | ^0.5.x | ^0.5.10 |
@tailwindcss/typography | ^0.5.x | ^0.5.16 |
autoprefixer, postcss, postcss-import | remove, unless your own code uses them |
2. Replace resources/css/craftable-pro.css with:
@import "tailwindcss" source(none);
@import "craftable-pro/../css/craftable-pro.css";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@source "../views/craftable-pro.blade.php";
@source "../js/craftable-pro";
@source "../../vendor/brackets/craftable-pro/resources/js";The @source lines are required. Tailwind 4 skips git-ignored folders such as
vendor/ when it looks for class names, so without them the admin's styles are
missing.
3. Delete craftable-pro.tailwind.config.js. If you changed it, for example
the primary colour, add the change to the end of resources/css/craftable-pro.css:
@theme {
--color-primary-500: #0ea5e9;
--color-primary-600: #0284c7;
}4. Update craftable-pro.vite.config.js: import Tailwind's Vite plugin,
add it to plugins, and empty the css.postcss.plugins list. Keep the empty
list: without it, Vite loads your app's own postcss.config.js, and a Tailwind 3
one (tailwindcss, autoprefixer) breaks the admin build:
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
plugins: [
laravel({ /* unchanged */ }),
tailwindcss(),
vue({ /* unchanged */ }),
],
css: {
postcss: {
plugins: [],
},
},
// ...
});While you are in this file, replace __dirname with import.meta.dirname in
the resolve.alias paths. Vite 8 warns about __dirname, because it won't work
once Vite's native config loader becomes the default.
5. Your own admin pages. The admin's built-in components are already
migrated. Pages that the CRUD generator created only use classes that work the
same in v4. If you wrote or changed pages in resources/js/craftable-pro
yourself, rename these classes:
| v3 | v4 |
|---|---|
shadow-sm / shadow | shadow-xs / shadow-sm |
rounded-sm / rounded | rounded-xs / rounded-sm |
outline-none | outline-hidden |
ring | ring-3 |
flex-shrink-0, flex-grow | shrink-0, grow |
!mt-2 (important prefix) | mt-2! (important suffix) |
bg-black bg-opacity-10 (also ring-opacity-*, text-opacity-*, …) | bg-black/10 |
The official upgrade tool (opens in a new tab) (npx @tailwindcss/upgrade)
can do this for you. Check its result: it renames the string "outline" to
"outline-solid" even where it is a prop value such as <Button variant="outline">,
and it can leave bg-opacity-* and ring-opacity-* unconverted. The rest of the
Tailwind upgrade guide (opens in a new tab) covers less common cases.
Colours from the admin theme (primary, secondary, gray, warning, danger,
success, info) look exactly as before. Other Tailwind colours used directly,
such as text-indigo-600, use Tailwind 4's slightly more vivid palette.
Then rebuild: npm install && npm run craftable-pro:build.
Update invitation links
Invitation links are now signed, time-limited URLs (see Users). This fixes a security issue where anyone who knew a user's e-mail could set that user's password through the invitation form. You only need to act if:
- you published
resources/js(craftable-pro-resourcestag): updatePages/Auth/InviteUser.vue. The page now receives anactionprop with the signed URL and must post the form there instead ofroute("craftable-pro.invite-user.store"); - you overrode the
invite_usere-mail template: use the new$urlvariable for the button link instead ofroute('craftable-pro.invite-user.create', $email).
Invitation e-mails sent before the upgrade contain unsigned links and stop working. Resend those invitations from the user list.
Fix the settings table (projects installed before v3)
This applies only if your project was installed when Craftable PRO used
spatie/laravel-settings 2, before Craftable PRO 3. It isn't new in v4, but it is
easy to miss. Projects installed later already have the right table.
The settings migration from version 2 has no unique index on (group, name).
Version 3, which Craftable PRO 3 and 4 require, saves settings with an upsert on
those two columns, so:
- PostgreSQL: saving settings throws, because the upsert needs a unique index to match on.
- MySQL / MariaDB: saving doesn't fail, but every save inserts new rows instead of updating the old ones. Your table may already contain duplicates.
Check your *_create_settings_table.php migration. If it has an index on group
but no unique(['group', 'name']), and locked has no default, add this
migration. It keeps the newest row of every duplicate, then adds the index and
gives locked a default of false, as in version 3:
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
$table = config('settings.repositories.database.table') ?? 'settings';
// Remove duplicates, keeping the newest row (the last saved value)
$duplicates = DB::table($table)
->select('group', 'name', DB::raw('MAX(id) as keep_id'))
->groupBy('group', 'name')
->havingRaw('COUNT(*) > 1')
->get();
foreach ($duplicates as $duplicate) {
DB::table($table)
->where('group', $duplicate->group)
->where('name', $duplicate->name)
->where('id', '!=', $duplicate->keep_id)
->delete();
}
$hasUnique = Schema::hasIndex($table, ['group', 'name'], 'unique');
Schema::table($table, function (Blueprint $blueprint) use ($hasUnique): void {
$blueprint->boolean('locked')->default(false)->change();
if (! $hasUnique) {
$blueprint->unique(['group', 'name']);
}
});
}
};Back up the settings table before running it on production, since it deletes
the duplicate rows.
Behaviour changes (no action needed)
- Social login errors ("Given e-mail domain is not enabled.", "Self registration is not allowed.") are now translated properly. Before, they were passed to the wrong translation helper.
- An invalid media upload path now always throws
InvalidUploadPath. On Laravel 13 it previously surfaced as a Flysystem exception.
Verify the upgrade
php artisan optimize:clear
php artisan testThen click through each generated listing in the admin and try search, sorting
and export. Any controller you missed in the controllers step fails on its index page with a
TypeError mentioning allowedFilters or allowedSorts.