Ehsan Bagherzadegan
Back to articles
10 min read

Building Dynamic Content Types in Filament with flex-fields: ACF-Style Fields, AI Agents, and a Headless API

The flex-fields package brings Advanced Custom Fields-style dynamic entities to Filament — define content types in the UI or code, query them via a headless REST API, and drive content workflows with Laravel AI SDK agents.

Filament has become the go-to admin panel for Laravel applications, but one capability has been missing: the ability to define custom content types and fields entirely through the UI — without writing migrations or models for every new entity. WordPress developers know this workflow as Advanced Custom Fields (ACF). Laravel developers have had to reach for packages like spatie/laravel-dynamic-fields or build their own EAV solutions.

ivanmercedes/flex-fields fills that gap. Released v0.6.2 on October 19, 2026, it brings ACF-style dynamic entities and fields to Filament v4/v5, with a schema builder for code-first workflows, a headless REST API, and — notably — first-class Laravel AI SDK integration.

The problem it solves

In a typical Filament application, adding a new content type means:

  1. Creating a migration
  2. Creating an Eloquent model
  3. Creating a Filament resource
  4. Defining the form schema in PHP
  5. Registering navigation and permissions

Multiply that by dozens of content types — products, events, team members, FAQs, testimonials — and the boilerplate adds up. Clients also ask to add fields after launch, which means more migrations and deployments.

flex-fields moves this to runtime. You define Entities (Products, Events, Employees) and Fields (text, select, image, repeater, relationship) in the admin UI or via a schema file. The package stores everything in a shared EAV (Entity-Attribute-Value) schema: ff_entities, ff_fields, ff_entity_records, ff_field_values. No migrations per entity.

Installation

composer require ivanmercedes/flex-fields
php artisan flex-fields:install
php artisan migrate

Register the plugin in your Filament panel provider:

use IvanMercedes\FlexFields\FlexFieldsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            FlexFieldsPlugin::make()
                ->showDashboardPage(true)
                ->showOverviewWidget(true)
                ->showEntitiesInMenu(true),
        ]);
}

The install command publishes the config, migrations, and assets. The migrations create the core EAV tables plus an ff_field_groups table for organizing fields into collapsible sections.

Two ways to define entities

Admin UI (runtime)

After installation, a Flex Fields section appears in your Filament navigation (if showEntitiesInMenu is enabled). Click Entities → Create Entity to define a new type — say, "Product." Then add fields: a text field for sku, a number field for price, an image field for photo, a rich text field for description, a select field for status with options draft|published|archived.

Each field supports:

  • Conditional visibility via showWhen (e.g., show discount_percentage only when on_sale is true)
  • Translatable values — store {"en": "Title", "es": "Título"} automatically
  • Validation rules defined through a visual builder
  • Default values and placeholder text
  • Field groups for collapsible form sections

Schema builder (code-first)

For version-controlled, reviewable definitions:

php artisan flex:make-schema Product

This creates database/flex-fields/schemas/Product.php:

return [
    'label' => 'Product',
    'plural_label' => 'Products',
    'icon' => 'heroicon-o-cube',
    'fields' => [
        ['name' => 'sku', 'type' => 'text', 'required' => true, 'unique' => true],
        ['name' => 'name', 'type' => 'text', 'required' => true, 'translatable' => true],
        ['name' => 'price', 'type' => 'number', 'decimals' => 2, 'min' => 0],
        ['name' => 'description', 'type' => 'rich_text', 'translatable' => true],
        ['name' => 'status', 'type' => 'select', 'options' => ['draft' => 'Draft', 'published' => 'Published']],
        ['name' => 'tags', 'type' => 'tags'],
        ['name' => 'related_products', 'type' => 'relationship', 'entity' => 'product'],
    ],
    'groups' => [
        ['name' => 'pricing', 'label' => 'Pricing', 'fields' => ['price', 'sale_price']],
    ],
];

Apply it:

php artisan flex:migrate

This approach keeps your entity definitions in git, reviewable in PRs, and deployable via CI — while still allowing runtime tweaks through the UI for non-technical editors.

Field types: 21 and counting

The package ships with 21 field types covering most admin panel needs:

Category Types
Text text, textarea, email, url, phone (with input masks), rich_text (TipTap)
Numbers number, slider
Selection select, multiselect, boolean (toggle), tags, color
Date/Time date, datetime, time
Media file, image (with Spatie Media Library optional)
Structured json (with JSON editor), repeater (nested field groups), address (structured sub-fields), links (title + URL arrays)
Relational relationship (to other flex entities or Eloquent models)

Repeaters are particularly powerful: they let you define a group of fields that can be repeated N times — perfect for "features list," "team members," or "pricing tiers" where each tier has name, price, and features.

Headless REST API

Enable the API in config (flex-fields.api.enabled = true) and you get:

GET    /api/flex/{entity}              # List records (supports filters, pagination)
GET    /api/flex/{entity}/{id}         # Single record
POST   /api/flex/{entity}              # Create
PUT    /api/flex/{entity}/{id}         # Update
DELETE /api/flex/{entity}/{id}         # Delete

Authentication uses Laravel Sanctum. The API respects entity-level permissions (see below). This makes flex-fields viable as a headless CMS backend for Nuxt, Next.js, or mobile apps.

Permissions and multi-tenancy

Per-entity permissions integrate with Filament Shield or spatie/laravel-permission:

// In a policy or gate
Gate::define('view_flex_entity', function ($user, $entity) {
    return $user->can("view {$entity->slug} records");
});

Gate::define('manage_flex_entity', function ($user, $entity) {
    return $user->hasRole('admin');
});

Multi-tenancy works out of the box with stancl/tenancy v3 — both per-tenant database and single-database (RLS) modes. Each tenant sees only their entities and records.

Record history and audit log

Every create/update/delete is recorded with a visual diff. The admin UI shows a timeline per record; clicking a change reveals old vs. new values side by side. One-click restore reverts a record to any previous version. This is built on the same EAV tables — no extra packages needed.

CSV/Excel import and export

The import flow:

  1. Download a template CSV with all field columns
  2. Fill it in
  3. Upload — flex-fields validates each row against field rules
  4. Preview shows valid/invalid rows with error messages
  5. Confirm to import

Export mirrors the same column structure. This is a huge time-saver for content migrations or bulk edits from spreadsheets.

AI SDK integration: the standout feature

This is where flex-fields gets interesting for 2026. The package ships with a dedicated Laravel AI SDK agent and toolset:

php artisan flex:agent  # Interactive CLI agent

Or programmatically:

use IvanMercedes\FlexFields\Ai\Agents\FlexFieldsAssistant;

$agent = new FlexFieldsAssistant;
$response = $agent->prompt('Show me the schema for the product entity');
$response = $agent->prompt('Create a product with SKU "ABC-123", price 49.99, and status published');
$response = $agent->prompt('Export all published products to CSV');

The agent exposes tools grouped by capability:

  • Read tools: list_entities, get_entity_schema, list_records, get_record
  • Content tools: create_record, update_record, delete_record
  • Publishing tools: bulk_publish, bulk_unpublish, schedule_publish
  • Destructive tools (require human approval): delete_entity, purge_records

Add tools to your own custom agents:

use IvanMercedes\FlexFields\Ai\FlexFieldsAi;

$agent = Agent::make()
    ->withTools([
        ...FlexFieldsAi::tools(['read', 'content']), // no destructive tools
    ]);

This lets you build AI-powered content workflows: "Generate product descriptions for all products missing a description," "Find products with price > 100 and tag them as premium," or "Create a blog post entity with standard SEO fields."

Developer ergonomics: the Facade and trait

For custom code outside Filament resources:

use IvanMercedes\FlexFields\Facades\FlexFields;

// Create a record
$record = FlexFields::entity('product')->createRecord(
    ['sku' => 'NEW-001', 'status' => 'draft'],      // base fields
    ['price' => 129.00, 'tags' => ['new', 'sale']]  // field values
);

// Query records
$products = FlexFields::entity('product')
    ->where('status', 'published')
    ->orderBy('created_at', 'desc')
    ->paginate(20);

Attach dynamic fields to any existing Eloquent model:

use IvanMercedes\FlexFields\Traits\HasFlexFields;

class Project extends Model
{
    use HasFlexFields;
    
    protected $flexEntity = 'project'; // links to flex entity
}

$project = Project::find(1);
$project->flexField('budget');        // get value
$project->setFlexField('budget', 50000); // set value
$project->flexFields();               // all fields as collection

This bridges traditional models with dynamic fields — useful when you have a core model (Project, User, Order) that needs extensible metadata.

Performance considerations

EAV schemas have a reputation for query complexity. flex-fields mitigates this with:

  • Field caching: Entity/field definitions are cached (configurable TTL, auto-invalidated on changes)
  • Eager loading: FlexFields::entity('product')->withFields(['price', 'tags'])->get() loads only needed fields
  • Indexes: The ff_field_values table has composite indexes on (entity_record_id, field_id) and (field_id, value) for common queries
  • Denormalized columns: Frequently queried fields (like status, published_at) can be promoted to dedicated columns via a migration — the package detects and uses them automatically

For high-traffic read paths, consider materialized views or a dedicated read replica. The headless API also supports ?fields=id,name,price sparse fieldsets to reduce payload size.

When to use it (and when not to)

Good fits:

  • Content-heavy sites where editors need to add fields without deploys
  • Multi-tenant applications where each tenant defines their own data model
  • Headless CMS backends for frontend frameworks
  • Prototyping — spin up an admin UI in minutes, extract to migrations later if needed
  • AI-assisted content workflows (the AI SDK integration is genuinely useful here)

Avoid when:

  • You have a fixed, known schema — standard Eloquent + Filament resources are simpler and faster
  • You need complex relational queries across dynamic fields (joins on EAV are painful)
  • You're building a high-write, low-read system where EAV overhead hurts
  • You need strict referential integrity enforced at the database level (foreign keys on dynamic fields aren't possible)

The package is pre-1.0 (v0.6.2), so the API may change. The author notes breaking changes are possible before v1.0. Pin the version in composer.json for production use.

A practical example: building a product catalog

Let's walk through a realistic setup. You need a product catalog with categories, variants, and SEO fields — editable by marketing, extensible by developers.

1. Define the entity via schema:

php artisan flex:make-schema Product
php artisan flex:make-schema Category
php artisan flex:migrate

2. Add fields in the schema files:

// Product.php
'fields' => [
    ['name' => 'sku', 'type' => 'text', 'required' => true, 'unique' => true],
    ['name' => 'name', 'type' => 'text', 'required' => true, 'translatable' => true],
    ['name' => 'description', 'type' => 'rich_text', 'translatable' => true],
    ['name' => 'price', 'type' => 'number', 'decimals' => 2],
    ['name' => 'compare_at_price', 'type' => 'number', 'decimals' => 2, 'showWhen' => 'on_sale'],
    ['name' => 'on_sale', 'type' => 'boolean'],
    ['name' => 'category', 'type' => 'relationship', 'entity' => 'category'],
    ['name' => 'images', 'type' => 'repeater', 'fields' => [
        ['name' => 'image', 'type' => 'image'],
        ['name' => 'alt', 'type' => 'text'],
        ['name' => 'sort_order', 'type' => 'number'],
    ]],
    ['name' => 'seo_title', 'type' => 'text'],
    ['name' => 'seo_description', 'type' => 'textarea'],
    ['name' => 'published_at', 'type' => 'datetime'],
],
'groups' => [
    ['name' => 'pricing', 'label' => 'Pricing', 'fields' => ['price', 'compare_at_price', 'on_sale']],
    ['name' => 'seo', 'label' => 'SEO', 'fields' => ['seo_title', 'seo_description'], 'collapsed' => true],
],

3. Marketing team adds a "warranty_period" field via the UI — no deployment needed.

4. Developer builds the frontend using the headless API:

// Nuxt/Next.js
const products = await $fetch('/api/flex/product', {
    query: { status: 'published', fields: 'id,name,price,images,seo_title' }
});

5. Content team uses the AI agent to bulk-generate SEO descriptions:

php artisan flex:agent
> Generate SEO descriptions for all products missing them, based on their name and description

Conclusion

flex-fields brings a missing piece to the Filament ecosystem: runtime-defined, user-extensible content structures with a developer-friendly code-first alternative. The EAV storage is a trade-off, but the caching, indexing, and denormalization options make it viable for real workloads. The AI SDK integration is not a gimmick — it turns the admin panel into a programmable content engine.

If you've ever wished Filament had ACF's flexibility, or if you're building a multi-tenant SaaS where each customer defines their own data model, flex-fields is worth a serious look. Install it in a fresh Laravel + Filament project, run php artisan flex:make-schema, and see how fast you can go from zero to a working admin panel with dynamic content types.

Sources