OpenParable
Skip to content
← Back to skills

Custom Fields Development

Development
custom-fields-development

Custom Fields Development is an Agent Skill for development published in the relaticle/relaticle repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Adds dynamic custom fields to Eloquent models without migrations using Filament integration. Use when adding the UsesCustomFields trait to models, integrating custom fields in Filament forms/tables/infolists, configuring field types, working with field validation, or managing feature flags for conditional visibility, encryption, and multi-tenancy.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/relaticle/relaticle/blob/HEAD/.github/skills/custom-fields-development/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/custom-fields-development, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Custom Fields Development

When to Use This Skill

Use when:

  • Adding custom fields capability to an Eloquent model
  • Integrating custom fields into Filament resources (forms, tables, infolists)
  • Configuring field types, validation, or visibility
  • Working with feature flags (encryption, multi-tenancy, sections)
  • Creating CSV importers/exporters with custom field support

Quick Start

1. Add Trait to Model

use Relaticle\CustomFields\Models\Concerns\UsesCustomFields;
use Relaticle\CustomFields\Models\Contracts\HasCustomFields;

class Contact extends Model implements HasCustomFields
{
    use UsesCustomFields;
}

2. Register Plugin in Panel

use Relaticle\CustomFields\CustomFieldsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            CustomFieldsPlugin::make()
                ->authorize(fn () => auth()->user()->isAdmin()),
        ]);
}

3. Publish and Run Migrations

php artisan vendor:publish --tag=custom-fields-migrations
php artisan migrate

Filament Integration

Use the CustomFields facade to generate form/table/infolist components.

Form Schema

use Relaticle\CustomFields\Facades\CustomFields;

public static function form(Form $form): Form
{
    return $form->schema([
        TextInput::make('name')->required(),
        // Add custom fields after regular fields
        CustomFields::form()->forSchema($form)->build(),
    ]);
}

Builder methods:

  • forSchema(Schema $schema) - Auto-detect model from form/infolist
  • forModel(Model|string $model) - Explicit model binding
  • only(['code1', 'code2']) - Include only specific fields
  • except(['code1']) - Exclude specific fields
  • withoutSections() - Flatten fields without section grouping

Table Columns and Filters

use Relaticle\CustomFields\Facades\CustomFields;

public static function table(Table $table): Table
{
    $customFields = CustomFields::table()->forModel(Contact::class);

    return $table
        ->columns([
            TextColumn::make('name'),
            ...$customFields->columns(),
        ])
        ->filters([
            ...$customFields->filters(),
        ]);
}

Infolist Entries

use Relaticle\CustomFields\Facades\CustomFields;

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        TextEntry::make('name'),
        CustomFields::infolist()->forSchema($infolist)->build(),
    ]);
}

CSV Import/Export

use Relaticle\CustomFields\Facades\CustomFields;

// In Importer class
public function getColumns(): array
{
    return [
        ImportColumn::make('name'),
        ...CustomFields::importer()->forModel(Contact::class)->columns()->toArray(),
    ];
}

// In Exporter class
public function getColumns(): array
{
    return [
        ExportColumn::make('name'),
        ...CustomFields::exporter()->forModel(Contact::class)->columns()->toArray(),
    ];
}

Available Field Types

TypeKeyData Storage
Texttexttext_value
Emailemailjson_value
Phonephonejson_value
Textareatextareatext_value
Rich Editorrich-editortext_value
Markdownmarkdown-editortext_value
Linklinkjson_value
Numbernumberinteger_value
Currencycurrencyfloat_value
Datedatedate_value
DateTimedate-timedatetime_value
Selectselectstring_value
Multi-Selectmulti-selectjson_value
Checkboxcheckboxboolean_value
Checkbox Listcheckbox-listjson_value
Radioradiostring_value
Toggletoggleboolean_value
Toggle Buttonstoggle-buttonsstring_value
Tags Inputtags-inputjson_value
Color Pickercolor-pickertext_value
File Uploadfile-uploadstring_value
Record Selectrecordjson_value

Field Type Key Naming

Convention: Use kebab-case for all field type keys.

For custom field types, use a project prefix to avoid conflicts:

ScenarioPatternExample
New custom type{project}-{name}acme-star-rating
Extended built-in{project}-{original}acme-rich-editor
Replace built-inSame keyrich-editor

Why prefix?

  • Avoids accidental override of built-in types
  • Future-proof against new package versions
  • Clear identification in database/UI
  • Safe for multi-vendor environments

Feature Flags

Configure in config/custom-fields.php using FeatureConfigurator:

use Relaticle\CustomFields\Enums\CustomFieldsFeature;
use Relaticle\CustomFields\FeatureSystem\FeatureConfigurator;

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

Feature Categories:

FeaturePurpose
FIELD_CONDITIONAL_VISIBILITYShow/hide fields based on other field values
FIELD_ENCRYPTIONEncrypt sensitive field values
FIELD_OPTION_COLORSColor badges for select/checkbox options
FIELD_VALIDATION_RULESEnable validation rule configuration
UI_TABLE_COLUMNSShow custom fields as table columns
UI_TABLE_FILTERSEnable filtering by custom fields
UI_TOGGLEABLE_COLUMNSAllow users to toggle column visibility
UI_FIELD_WIDTH_CONTROLControl field width in forms
SYSTEM_MANAGEMENT_INTERFACEAdmin page for managing fields
SYSTEM_SECTIONSOrganize fields into sections
SYSTEM_MULTI_TENANCYTenant isolation for fields

Configuration

Entity Discovery

use Relaticle\CustomFields\EntitySystem\EntityConfigurator;

'entity_configuration' => EntityConfigurator::configure()
    ->discover(app_path('Models'))
    ->exclude(['User', 'Team'])
    ->cache(enabled: true, ttl: 3600),

Field Type Control

use Relaticle\CustomFields\FieldTypeSystem\FieldTypeConfigurator;

'field_type_configuration' => FieldTypeConfigurator::configure()
    ->enabled(['text', 'email', 'select', 'number'])
    ->disabled(['file-upload'])
    ->discover(true)
    ->cache(enabled: true),

Custom Tenant Resolver

For multi-tenancy outside Filament panels:

use Relaticle\CustomFields\CustomFields;

// In AppServiceProvider::boot()
CustomFields::resolveTenantUsing(fn () => auth()->user()?->team_id);

Programmatic Field Access

// Get all custom fields for a model
$fields = $contact->customFields()->get();

// Get a specific field value
$value = $contact->getCustomFieldValue($customField);

// Save a field value
$contact->saveCustomFieldValue($customField, 'new value');

// Save multiple field values
$contact->saveCustomFields([
    'industry' => 'Technology',
    'company_size' => 'Enterprise',
]);

Database Schema

Four tables are created:

  • custom_field_sections - Optional grouping of fields
  • custom_fields - Field definitions (name, code, type, validation)
  • custom_field_options - Choice options for select/checkbox fields
  • custom_field_values - Polymorphic storage of field values

Values are stored in type-specific columns: string_value, text_value, integer_value, float_value, boolean_value, date_value, datetime_value, json_value.

Custom Models

Override default models for custom behavior:

use Relaticle\CustomFields\CustomFields;

// In AppServiceProvider::boot()
CustomFields::useCustomFieldModel(MyCustomField::class);
CustomFields::useValueModel(MyCustomFieldValue::class);
CustomFields::useOptionModel(MyCustomFieldOption::class);
CustomFields::useSectionModel(MyCustomFieldSection::class);

Register Custom Field Types

use Relaticle\CustomFields\CustomFieldsPlugin;

CustomFieldsPlugin::make()
    ->registerFieldTypes([
        MyCustomFieldType::class,
    ])

Custom field types must extend Relaticle\CustomFields\FieldTypeSystem\BaseFieldType.