Getting Started
Upgrading
Upgrade guide for Flowforge
From v3.x to v4.x
v4.x upgrades Filament support from 4.x to 5.x. No database or code changes required.
Requirements
- Filament 5.x (was 4.x)
- PHP 8.3+
- Laravel 12+
Upgrade Steps
composer require relaticle/flowforge:^4.0
Review the Filament 5 Upgrade Guide if you customized Filament components.
No Changes Required
- Board configuration API unchanged
- Position column type unchanged
- All existing board code works without modification
From v2.x to v4.x
This covers all breaking changes from v2.x directly to v4.x. Includes database migration.
Requirements
- PHP 8.3+ (was 8.2+)
- Laravel 12+ (was 10+)
- Filament 5.x (was 3.x)
- New:
ext-bcmathPHP extension
High Impact Changes
Position Column Type Changed
The flowforgePositionColumn() macro now creates DECIMAL(20,10) instead of VARCHAR.
Quick upgrade (resets card order):
public function up(): void
{
Schema::table('tasks', function (Blueprint $table) {
$table->dropColumn('position');
});
Schema::table('tasks', function (Blueprint $table) {
$table->flowforgePositionColumn();
});
}
Then run:
php artisan flowforge:repair-positions
Preserve card order: See v2.x to v3.x section below for detailed migration.
Medium Impact Changes
BCMath Extension Required
# Ubuntu/Debian
sudo apt-get install php-bcmath
Factory Code Updates
If you used position service directly:
// Before (v2.x)
use Relaticle\Flowforge\Services\Rank;
$position = Rank::forEmptySequence()->get();
// After (v4.x)
use Relaticle\Flowforge\Services\DecimalPosition;
$position = DecimalPosition::forEmptyColumn();
No Changes Required
- Board configuration API unchanged
- Card/column actions unchanged
- Customization options unchanged
From v2.x to v3.x
v3.x changes how positions are stored in the database. A migration is required.
Requirements
- PHP 8.3+ (was 8.2+)
- Laravel 11+ (was 10+)
- New:
ext-bcmathPHP extension
High Impact Changes
Position Column Type Changed
The flowforgePositionColumn() macro now creates a DECIMAL(20,10) column instead of VARCHAR. You must migrate existing position columns.
Quick upgrade (resets card order):
public function up(): void
{
Schema::table('tasks', function (Blueprint $table) {
$table->dropColumn('position');
});
Schema::table('tasks', function (Blueprint $table) {
$table->flowforgePositionColumn();
});
}
Then run:
php artisan flowforge:repair-positions
Preserve card order:
public function up(): void
{
// Add temporary column
Schema::table('tasks', function (Blueprint $table) {
$table->decimal('position_new', 20, 10)->nullable();
});
// Copy order (positions will be regenerated by repair command)
DB::statement('UPDATE tasks SET position_new = CAST(position AS DECIMAL(20,10))');
// Swap columns
Schema::table('tasks', function (Blueprint $table) {
$table->dropColumn('position');
});
Schema::table('tasks', function (Blueprint $table) {
$table->renameColumn('position_new', 'position');
});
}
Then run:
php artisan flowforge:repair-positions
# Select "regenerate" strategy
Medium Impact Changes
BCMath Extension Required
Install the BCMath PHP extension:
# Ubuntu/Debian
sudo apt-get install php-bcmath
# Verify
php -m | grep bcmath
Low Impact Changes
New Artisan Commands
v3.x adds diagnostic commands:
php artisan flowforge:diagnose-positions # Check for issues
php artisan flowforge:rebalance-positions # Redistribute positions
No Changes Required
- Board configuration API unchanged
- Card/column actions unchanged
- Customization options unchanged
- All existing board code works without modification
Advanced: Factory Code Updates
Only relevant if you directly used the
Rank service in your code.If you used Flowforge's position service in factories or custom code:
// Before (v2.x)
use Relaticle\Flowforge\Services\Rank;
$position = Rank::forEmptySequence()->get();
$position = Rank::after($lastRank)->get();
// After (v3.x)
use Relaticle\Flowforge\Services\DecimalPosition;
$position = DecimalPosition::forEmptyColumn();
$position = DecimalPosition::after($lastPosition);
Most users don't need this - the package handles positions automatically during drag-and-drop.