FieldKit Core

⚠️ Work In Progress: This package is currently under active development and not yet ready for production use.

Framework-agnostic core package for dynamic, admin-manageable form fields with multi-source support and external system integration.

Features

• Multi-Source Support - Load field definitions from Database, JSON config, or PHP classes
• Handler System - Flexible external system integration (Ameax, Mailchimp, APIs) with sync/async processing
• Auto-Discovery - Automatically discover and register input types and transformers
• Dual-Storage - Local JSON storage + external system handlers
• Type-Safety - Compatibility system prevents data loss during field type changes
• Conditional Visibility - Show/hide fields based on other field values
• Transformers - Safe value transformation (e.g., boolean → "1"/"0" for external systems)
• Framework-Agnostic - Core logic independent of UI framework

Installation

Via Composer (when published)

composer require ameax/fieldkit-core

Local Development Setup

For local development, add the package as a path repository in your main project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/fieldkit-core"
        }
    ]
}

Then install:

composer require ameax/fieldkit-core:@dev

Publish Configuration and Migrations

# Publish the configuration file
php artisan vendor:publish --tag="fieldkit-core-config"

# Publish and run migrations
php artisan vendor:publish --tag="fieldkit-core-migrations"
php artisan migrate

Configuration

After publishing, configure the package in config/fieldkit.php:

return [
    // Input type registry
    'input_types' => [
        'text' => \Ameax\FieldkitCore\Inputs\FieldKitTextInput::class,
        'email' => \Ameax\FieldkitCore\Inputs\FieldKitEmailInput::class,
        'number' => \Ameax\FieldkitCore\Inputs\FieldKitNumberInput::class,
        'textarea' => \Ameax\FieldkitCore\Inputs\FieldKitTextareaInput::class,
        'checkbox' => \Ameax\FieldkitCore\Inputs\FieldKitCheckboxInput::class,
        'select' => \Ameax\FieldkitCore\Inputs\FieldKitSelectInput::class,
        'radio' => \Ameax\FieldkitCore\Inputs\FieldKitRadioInput::class,
    ],
    
    // Definition source priorities
    'definition_sources' => [
        'config' => ['priority' => 200],    // Config First principle
        'database' => ['priority' => 100],
        'json' => [
            'priority' => 50,
            'path' => storage_path('fieldkit'),
        ],
    ],
    
    // Handler classes for external system integration
    'handlers' => [],
];

Basic Usage

1. Configure Form with Handlers

// config/fieldkit-forms.php
return [
    'customer_registration' => [
        'model' => \App\Models\Customer::class,
        'json_column' => 'fieldkit_data',
        'handlers' => [
            \App\FieldKit\Handlers\AmeaxCustomerHandler::class,
        ],
        'fields' => [
            [
                'key' => 'newsletter',
                'type' => 'checkbox',
                'label' => 'Newsletter subscription',
                'store_in_json' => true,
                'mappings' => [
                    [
                        'adapter' => 'ameax_column',
                        'target_table' => 'customer',
                        'target_column' => 'xcu_newsletter',
                        'transformer' => 'boolean',
                    ],
                ],
            ],
        ],
    ],
];

2. Store Form Values

use Ameax\FieldkitCore\Services\FieldKitService;

$service = app(FieldKitService::class);

$service->storeFieldValues(
    purposeToken: 'customer_registration',
    formData: ['newsletter' => true],
    model: $customer
);

// Result:
// 1. Local: $customer->fieldkit_data['newsletter'] = true (persistent)
// 2. Handler: AmeaxCustomerHandler triggered (queued)

3. Create a Handler

<?php

namespace App\FieldKit\Handlers;

use Ameax\FieldkitCore\Contracts\FieldKitMappingHandlerInterface;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Collection;

class AmeaxCustomerHandler implements FieldKitMappingHandlerInterface
{
    public function supports(string $adapter): bool
    {
        return $adapter === 'ameax_column';
    }

    public function shouldQueue(): bool
    {
        return true;  // Run async via queue
    }

    public function handle(Model $model, Collection $mappings, array $formData): void
    {
        // Process mappings and sync to external system
        $data = $this->transformMappings($mappings, $formData);
        $this->ameax->updateCustomer($model->id, $data);
    }
}

Documentation

For full documentation, see the FieldKit Documentation.

UI Integration

For Filament admin panel integration, install:

composer require ameax/fieldkit-filament

See fieldkit-filament for details.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Michael Schmidt
• All Contributors

License

The MIT License (MIT). Please see License File for more information.