Flex Fields Laravel Package

Getting Started

This is a 0.7.x update. The provided 0.7.1 notes are a bugfix release for field caching on newer Laravel applications: active entity fields are cached as plain attributes and rebuilt as models when read. Upgrade especially if record forms are failing with a TypeError on a new Laravel app where cached PHP classes are not unserialized (cache.serializable_classes). The repeater sub-field rendering and is_shown_in_list table-column behavior from the 0.6.x line still apply.

Minimal steps:

1. Update the package and clear cached config/assets:

   composer update <vendor>/<package>
   php artisan optimize:clear
   

2. If you cache config, rebuild it after upgrade:

   php artisan config:cache
   

3. If you publish package config/migrations, check for new published files. The 0.7.1 notes do not mention a schema change, so no data migration is required for the cache fix.
4. Open the custom field form in the admin panel and verify:
   • Repeater fields display their declared sub-fields.
   • Fields marked “Show in table” appear as columns in the records table.
   • Record forms load without a TypeError on newer Laravel apps.
5. First use case: add a custom field to a resource, mark it as shown in the list, confirm it renders and searches correctly in the records table, then open an existing record form to confirm the field cache rebuild works.

Where to look first:

• Record forms if you see TypeError on a new Laravel app: check the package version first, then clear caches.
• The custom field form: this is where is_shown_in_list, searchability, field groups, conditional visibility and validation are configured.
• The records table: confirm supported field types render as columns.
• Existing repeater data: verify old items still render and new API/import payloads use declared sub-field keys.
• The refreshed README: includes screenshots for translatable fields, conditional visibility, validation/conditional builders, record history, CSV import preview and field groups.

Implementation Patterns

Treat custom fields as configuration-driven schema: define fields in the admin form rather than hard-coding every form input. This lets you add fields, group them, and expose them in tables without a deploy.

Common patterns:

• Resource form integration: render the package’s custom fields section/component inside your Filament resource form. Use field groups to keep long forms organized.
• Table visibility: set is_shown_in_list on fields that should become columns. In the current line these render for boolean, image, color and formatted text columns. Mark the field searchable if you want it searchable in the table.
• Repeater payloads: define repeater sub-fields in the admin form, then create repeater items through APIs, imports or AI tools using those declared sub-field keys. This is the expected format after the 0.6.1 repeater fix.
• Conditional forms: pair conditional visibility with the validation/conditional builder so fields appear only when relevant and validation follows the same rules. Test both admin submissions and API/import paths.
• Translatable fields: use translatable fields where content varies by locale; confirm table columns display the expected locale value.
• Auditability: use record history to inspect changes to custom field values, especially when imports or API integrations write data.
• Import workflows: use the CSV import preview to validate mappings before committing. Ensure repeater columns and custom field keys match the declared field structure.
• AI/tooling integration: generate payloads with the same field keys used by the admin form. Do not generate the older ff_-prefixed repeater keys.
• Cache-aware field loading: in 0.7.1, active fields are cached as plain attributes and hydrated back into models when read. Treat the cache as an internal package detail; use package APIs rather than reading raw cached field payloads.
• Upgrade and cache hygiene: after package updates, clear optimized caches. On new Laravel apps, confirm you are on 0.7.1 before debugging form-schema issues, because the older cache behavior could surface as a TypeError in record forms.

A useful integration rule: keep one canonical field-key convention across admin forms, APIs, imports and AI-generated data. The 0.6.1 repeater fix makes the admin form expect declared sub-field keys; older stored data is normalized when read.

Gotchas and Tips

• Field cache TypeError on new Laravel apps: older cached active fields could come back as incomplete classes when Laravel does not unserialize PHP classes from cache (cache.serializable_classes). 0.7.1 fixes this by caching plain attributes and rebuilding models on read. Upgrade rather than relying only on a cache clear.
• Older cache entries are rebuilt: entries cached by older package versions are rebuilt in 0.7.1. Still clear optimized caches after deploy, especially if you use config/route/view caching.
• Raw cache consumers: do not assume the package’s cached active fields are directly usable Eloquent models. In 0.7.1 the cached representation is plain attributes; use package APIs if you need hydrated field definitions.
• Repeater key mismatch: older versions stored repeater items with ff_-prefixed sub-field keys. The 0.6.1+ line normalizes those when reading, so old records should still display. Any custom writers — API endpoints, importers, AI tools — should now write declared sub-field keys, not prefixed keys.
• No data migration required for repeater reads: the package normalizes old repeater data on read. If other systems read the raw stored JSON, they may still see mixed old/new key formats; normalize at the integration boundary if needed.
• Table columns are type-limited: “Show in table” renders boolean, image, color and formatted text columns in the current line. If a field does not appear, check both is_shown_in_list and whether its field type has a table-column renderer.
• Searchability is separate: a field shown in the table is only searchable when it is also marked searchable. Check both toggles.
• Toggle location: the “Show in table” toggle is available in the custom field form. If it seems missing, confirm you are editing the field definition, not a record value.
• Conditional visibility and validation: hidden fields can behave differently between admin forms and API/import submissions. Test validation rules with conditions active and inactive, and keep API validation aligned with the builder configuration.
• Translatable table values: verify which locale is displayed in table columns and in record history. Do not assume the current admin locale is the stored fallback.
• Image fields: image columns depend on valid stored paths/URLs. The README’s absolute image URLs are for documentation rendering only and do not change how record image fields are stored.
• After upgrade: clear optimized caches and republish front-end assets if your setup requires it. Filament plugin upgrades often need asset/config refreshes even when the package release is a patch.
• Debugging form failures: if a record form fails with TypeError on a new Laravel app, check the package version and clear caches before changing field definitions or form schema.
• Debugging table visibility: start with the field definition (is_shown_in_list, searchable flag, field type), then inspect the resource table registration, then clear caches.
• Extension points: custom field types and form/table renderers are the places to extend when the built-in column types are insufficient. Keep custom renderers consistent with the declared field keys used by repeaters and imports, and avoid caching models directly where cache.serializable_classes is restrictive.