Skip to main content
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. Configuration Updates (Required)

Custom Fields v2 introduces improved field type management using fluent configurators. You must update your config/custom-fields.php to use the new configuration format: 
'field_type_configuration' => FieldTypeConfigurator::configure()
    ->enabled([])                   // Empty = all enabled
    ->disabled(['rich-editor'])     // Disable specific field types
    ->discover(true)
    ->cache(enabled: false, ttl: 3400),

​
5. Field Type Architecture Changes

Custom Fields v2 now uses BaseFieldType with FieldSchema for cleaner field type definitions. If you have custom field types, update them:
  • Base Class: Extend BaseFieldType (instead of implementing interface directly)
  • Configuration: Return FieldSchema from configure() method
  • Benefits: Less boilerplate, better type safety, cleaner API
class CustomFieldType extends BaseFieldType
{
    public function configure(): FieldSchema
    {
        return FieldSchema::string()
            ->key('custom-field')
            ->label('Custom Field')
            ->icon('heroicon-o-star')
            ->formComponent(TextInput::class)
            ->priority(50);
    }
}

​
6. 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

Replace with the new builder API:
// Old
CustomFieldsComponent::make()

// New
CustomFields::form()
->forModel($form->getRecord())
->build()
The trait has moved to a new namespace:
// Old namespace
use Relaticle\CustomFields\Filament\Tables\Concerns\InteractsWithCustomFields;

// New namespace (still works!)
use Relaticle\CustomFields\Concerns\InteractsWithCustomFields;

// Or migrate to builder API for more control
...CustomFields::table()
->forModel($table->getModel())
->columns()
Check these common issues:
  • Model must implement HasCustomFields and use UsesCustomFields trait
  • Use forModel() not forResource() in builders
  • Clear caches after upgrading
  • Verify custom fields exist in database
Remember to use spread operator and call the right methods:
->columns([
// Your columns
...CustomFields::table()
->forModel($table->getModel())
->columns(), // Note: columns() not build()
])
->filters([
// Your filters
...CustomFields::table()
->forModel($table->getModel())
->filters(), // Note: filters() not build()
])

​
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