Custom Fields v2 introduces a new fluent builder API that simplifies integration while providing more flexibility.

​
Quick Upgrade

The easiest way to upgrade is using the built-in upgrade command: 
composer require relaticle/custom-fields:"^2.0" -W
vendor/bin/custom-fields-upgrade
This command handles all necessary migrations and cache clearing automatically.

​
Manual Upgrade Steps

​
1. Update Composer

Update your composer.json to require v2: 
{
    "require": {
        "relaticle/custom-fields": "^2.0"
    }
}
Then run: 
composer update relaticle/custom-fields

​
2. Database Changes

Custom Fields v2 adds one new column:
  • settings JSON column in custom_field_options table
The upgrade command handles this automatically. If you need to create the migration manually, add a settings JSON column to the custom_field_options table.

​
3. Update Your Code

The main change in v2 is the move from component-based integration to a fluent builder API.

​
Filament Resources - Forms

// Old v1 syntax
use Relaticle\CustomFields\Filament\Forms\Components\CustomFieldsComponent;
use Filament\Forms\Form;

public static function form(Form $form): Form
{
    return $form
    ->schema([
    // Your fields
    TextInput::make('name'),
    TextInput::make('price'),

    // Custom fields component
    CustomFieldsComponent::make(),
    ]);
}

​
Filament Resources - Tables

// Old v1 syntax
use Relaticle\CustomFields\Filament\Tables\Concerns\InteractsWithCustomFields;
use Filament\Resources\Pages\ListRecords;

class ListProducts extends ListRecords
{
    use InteractsWithCustomFields;

    // Custom fields are automatically added
}

​
Filament Resources - Infolists

// Old v1 syntax - Using CustomFieldsInfolists component
use Relaticle\CustomFields\Filament\Infolists\CustomFieldsInfolists;
use Filament\Infolists\Infolist;

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist
    ->schema([
    // Your entries
    TextEntry::make('name'),
    TextEntry::make('price'),

    // Custom fields component
    CustomFieldsInfolists::make()
    ->columnSpanFull(),
    ]);
}

​
4. Final Steps

After updating your code, clear all caches: 
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan filament:cache-components

​
New Features in v2

​
Fluent Builder API

The new builder API provides more control and flexibility: 
// Forms - returns a single component
CustomFields::form()
    ->forModel($record)
    ->except(['field_code']) // Exclude specific fields
    ->only(['field_code']) // Include only specific fields
    ->build()

// Tables - returns collections
CustomFields::table()
    ->forModel(Product::class)
    ->columns() // Returns column collection
    
// Filters
CustomFields::table()
    ->forModel(Product::class)
    ->filters() // Returns filter collection

// Infolists - flexible output
CustomFields::infolist()
    ->forModel($record)
    ->build() // Returns single Grid component
    // OR
    ->values() // Returns collection of components

​
Breaking Changes

​
Component-Based Integration Changes

V2 introduces a new builder pattern while maintaining backward compatibility: Forms:
  • CustomFieldsComponent → Removed, use CustomFields::form()->forSchema($schema)->build()
Tables (two options):
  • Option 1 (Recommended): Use builder API: CustomFields::table()->forModel($model)->columns() and ->filters()
  • Option 2: Continue using InteractsWithCustomFields trait with updated namespace: Relaticle\CustomFields\Concerns\InteractsWithCustomFields
Infolists:
  • CustomFieldsInfolists → Removed, use CustomFields::infolist()->forSchema($schema)->build()

​
API Changes

  • New builder pattern introduced (recommended approach)
  • InteractsWithCustomFields trait moved from Relaticle\CustomFields\Filament\Tables\Concerns\InteractsWithCustomFields to Relaticle\CustomFields\Concerns namespace
  • All builders use forModel() method (not forResource())
  • Table builder returns separate columns() and filters() collections
  • Infolist can return either build() for single component or values() for collection
  • Field type system completely rewritten

​
Troubleshooting

​
Migration Checklist

  • Backup your application
  • Run composer require relaticle/custom-fields:"^2.0" -W
  • Run vendor/bin/custom-fields-upgrade
  • Update forms: CustomFieldsComponent::make() → CustomFields::form()->forSchema($schema)->build()
  • Update tables: Either update InteractsWithCustomFields namespace OR migrate to ...CustomFields::table()->forModel($model)->columns()
  • Update infolists: CustomFieldsInfolists::make() → CustomFields::infolist()->forModel($model)->build()
  • Clear caches and test thoroughly