Custom Fields Laravel Package

title: Configuration description: Configure all aspects of the Custom Fields package navigation: icon: i-lucide-settings

Overriding Models

The Custom Fields package allows you to replace the default models with your own implementations.

Registering Custom Models

Register your custom models using the CustomFields class:

use Relaticle\CustomFields\CustomFields;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        CustomFields::useCustomFieldModel(YourCustomField::class);
        CustomFields::useValueModel(YourCustomFieldValue::class);
        CustomFields::useOptionModel(YourCustomFieldOption::class);
        CustomFields::useSectionModel(YourCustomFieldSection::class);
    }
}

Date Display Formats

By default, date and date-time fields use different formats depending on context (forms use Y-m-d, tables use M j, Y, etc.). You can set a single consistent format across all Filament components.

Via Plugin (recommended)

use Relaticle\CustomFields\CustomFieldsPlugin;

CustomFieldsPlugin::make()
    ->dateDisplayFormat('m/d/Y')
    ->dateTimeDisplayFormat('m/d/Y h:i A')

Via Facade

use Relaticle\CustomFields\CustomFields;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        CustomFields::useDateDisplayFormat('m/d/Y');
        CustomFields::useDateTimeDisplayFormat('m/d/Y h:i A');
    }
}

The configured format applies to:

::alert{type="info"} This only affects how dates are displayed. Storage formats (Y-m-d and Y-m-d H:i:s) remain unchanged. ::

Pass null to reset back to component defaults:

CustomFields::useDateDisplayFormat(null);

Configuration File

The configuration file (config/custom-fields.php) allows you to customize all aspects of the Custom Fields package. It uses modern fluent configurators for type safety and better IDE support.

Entity Configuration

Configure which models can have custom fields:

'entity_configuration' => EntityConfigurator::configure()
    ->discover(app_path('Models'))  // Auto-discover models in this path
    ->cache(true),                  // Enable caching for performance

Field Types Configuration

Control which field types are available:

'field_type_configuration' => FieldTypeConfigurator::configure()
    ->enabled([])                   // Empty = all enabled
    ->disabled(['file-upload'])     // Disable specific field types
    ->discover(true)                // Auto-discover custom field types
    ->cache(enabled: false, ttl: 3400),

Features Configuration

Configure package features using the enum-based system:

'features' => FeatureConfigurator::configure()
    ->enable(
        CustomFieldsFeature::FIELD_CONDITIONAL_VISIBILITY,
        CustomFieldsFeature::FIELD_ENCRYPTION,
        CustomFieldsFeature::FIELD_OPTION_COLORS,
        CustomFieldsFeature::UI_TABLE_COLUMNS,
        CustomFieldsFeature::UI_TOGGLEABLE_COLUMNS,
        CustomFieldsFeature::UI_TABLE_FILTERS,
        CustomFieldsFeature::SYSTEM_MANAGEMENT_INTERFACE
    )
    ->disable(
        CustomFieldsFeature::SYSTEM_MULTI_TENANCY
    ),

Management Interface

Configure the custom fields management page:

'management' => [
    'slug' => 'custom-fields',      // URL slug
    'navigation_sort' => -1,        // Navigation sort order
    'navigation_group' => true,     // Group in navigation
    'cluster' => null,              // Optional cluster assignment
],

Database Configuration

Customize table names and paths:

'database' => [
    'migrations_path' => database_path('custom-fields'),
    'table_names' => [
        'custom_field_sections' => 'custom_field_sections',
        'custom_fields' => 'custom_fields',
        'custom_field_values' => 'custom_field_values',
        'custom_field_options' => 'custom_field_options',
    ],
    'column_names' => [
        'tenant_foreign_key' => 'tenant_id',
    ],
],

Available Features

The package supports these features that can be enabled/disabled:

::alert{type="info"} If your custom models include tenant-specific scoping logic, you'll need to register a custom tenant resolver to ensure validation works correctly. ::

Configuration Examples

Restricting Field Types

Limit available field types in production:

'field_type_configuration' => FieldTypeConfigurator::configure()
    ->enabled([
        'text',
        'textarea',
        'number',
        'select',
        'checkbox',
        'date',
    ])
    ->disabled([
        'rich-editor',      // Disable rich content editors
        'markdown-editor',  // Disable markdown editor
        'file-upload',      // Disable file uploads
    ]),

Performance Configuration

Optimize for production:

'entity_configuration' => EntityConfigurator::configure()
    ->discover(app_path('Models'))
    ->cache(env('CUSTOM_FIELDS_CACHE', true)),  // Enable caching

'field_type_configuration' => FieldTypeConfigurator::configure()
    ->cache(enabled: true, ttl: 3600),          // Cache field types

Multi-Tenancy Setup

Enable tenant isolation:

'features' => FeatureConfigurator::configure()
    ->enable(
        CustomFieldsFeature::SYSTEM_MULTI_TENANCY,
        // ... other features
    ),

'database' => [
    // ... other config
    'column_names' => [
        'tenant_foreign_key' => 'tenant_id',  // Your tenant foreign key
    ],
],

Custom Tenant Resolution

If you've extended the CustomField or CustomFieldSection models with custom tenant handling (e.g., custom global scopes), register a tenant resolver to ensure validation and queries respect your custom logic:

use Relaticle\CustomFields\CustomFields;

// In your AppServiceProvider or plugin boot method
CustomFields::resolveTenantUsing(fn() => auth()->user()?->company_id);

::alert{type="success"} The custom resolver takes priority over Filament's built-in tenancy, giving you complete control over tenant resolution. ::

Common Patterns:

// Auth-based tenancy
CustomFields::resolveTenantUsing(fn() => auth()->user()?->company_id);

// Header-based (APIs)
CustomFields::resolveTenantUsing(fn() => request()->header('X-Tenant-ID'));

// Session-based
CustomFields::resolveTenantUsing(fn() => session('current_tenant_id'));

::alert{type="success"} Need help? Check that your resolver returns the correct tenant ID using TenantContextService::getCurrentTenantId() in your application. ::

Best Practices

Performance Optimization

1. Enable Caching: Always enable caching in production
2. Limit Discovery: Only discover models you need
3. Restrict Field Types: Only enable field types you use

Security Considerations

1. Disable Unused Features: Turn off features you don't need
2. Restrict Field Types: Disable potentially unsafe field types like rich editors
3. Enable Multi-Tenancy: Always enable in multi-tenant applications

Development vs Production

Use environment variables for flexible configuration:

'entity_configuration' => EntityConfigurator::configure()
    ->discover(app_path('Models'))
    ->cache(env('CUSTOM_FIELDS_CACHE', !app()->isLocal())),

'field_type_configuration' => FieldTypeConfigurator::configure()
    ->cache(enabled: env('CUSTOM_FIELDS_CACHE_TYPES', true)),