Getting Started
Upgrading
Upgrade guide for Flowforge
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.