Custom Fields Laravel Package

Getting Started

• Install into an existing AureusERP/Laravel app: composer require aureuserp/custom-fields. If you're working from source, add the VCS/path repository entry first and require @dev.
• Laravel auto-discovers the service provider. Confirm it is registered (php artisan about or config/app.php) and that the package's migrations are picked up — run php artisan migrate before touching any UI.
• Publish what you need only if you intend to change defaults: php artisan vendor:publish --provider="AureusERP\CustomFields\CustomFieldsServiceProvider". Typical publishable assets are the config file, migrations, and translations. Publishing migrations is a one-way door — do it before the first production migrate, not after.
• Where to look first, in this order:
  1. config/custom-fields.php — table names, supported field types, model/morph configuration.
  2. src/Models/ — the custom field definition model and the value-storage model; this tells you whether values live in a JSON column or a separate EAV table.
  3. src/Enums/ (or wherever field types are enumerated) — the authoritative list of what you can add.
  4. src/Filament/ — the form/table integration, since this package is designed to plug into Filament resources.
  5. database/migrations/ — column types and indexes, which dictate what you can query efficiently later.
• First use case: add a single field to one entity end to end. Pick something low-risk like vat_number on Customer. Create the definition (through the admin UI if the package ships one, otherwise via the model), attach it to the customers entity, open a Customer form, save a value, then re-open and confirm it round-trips. That single loop exercises definition storage, schema rendering, validation, persistence, and hydration — if any of those are broken you'll find out immediately rather than three entities deep.

Implementation Patterns

Treat definitions as data, not code. The core pattern is that field definitions are rows, not migrations. That means:

• Ship a seeder for definitions your app depends on, so a fresh environment and CI both get the same shape. Seeders should be idempotent (updateOrCreate keyed on entity + code) because you will re-run them.
• Keep the code/slug stable and immutable once values exist. Users edit labels freely; the code is the join key between definition and stored value.

Attaching fields to a model. Most implementations of this pattern use either a polymorphic relation or an entity/table-name string. Pick one convention and enforce it:

• If polymorphic, register a morph map (Relation::enforceMorphMap([...])) in a service provider before any definitions are created. Without it, renaming a model class silently orphans every value row. This is the single highest-cost mistake in this pattern.
• If keyed by table name, centralise the mapping in a config array so customers isn't hardcoded across a dozen resources.

Rendering in Filament. The usual integration is to merge dynamically built components into an existing form(Schema $schema):

• Build the custom field components in a helper/service and append them after the resource's own fields, ideally inside a Section or Fieldset so they're visually separated from first-class columns.
• For the table, resolve column visibility from the definitions and add TextColumns with the same labels. Consider toggleable(isToggledHiddenByDefault: true) — custom fields multiply quickly and will wreck table density.
• Because definitions are runtime data, any Filament caching of schemas matters. If the panel caches components, add a cache-busting step when a definition is created/updated/deleted.

Validation. Derive rules from the definition's type and its validation/options payload rather than hand-writing them. A small CustomFieldRuleFactory that maps type → rules (numeric, date, in: from options, max: from config) pays for itself the first time someone adds a "percentage" field and types abc. Apply the same rules in the Filament form and in any API/import path — the package will not enforce them for you at the persistence layer.

Reading and writing values. Encapsulate access in a trait (HasCustomFields) on the consuming models with:

• getCustomField(string $code, $default = null)
• setCustomField(string $code, $value)
• customFieldValues(): array returning code → value for form hydration.

Never let resources touch the value table directly; the moment storage moves from JSON to EAV (or gains a company_id scope) you want one place to change.

Multi-tenancy / company scoping. In an ERP context, check whether definitions and values are scoped per company. If they are, every query path — UI, API, exports, seeders — needs the scope applied. If the package does not scope and you need it, wrapping the definition model in a global scope is far easier before you have production data than after.

Import/export and API surface. Custom fields are a common source of "the CSV import dropped my field" bugs. Map user-facing labels back to codes in one place and reuse it for imports, exports, and API payloads. Validate on import that the definition exists and is active.

Gotchas and Tips

• Definitions added after boot aren't visible. If the panel or a form schema is cached, a newly created field won't appear until you clear it. Keep a php artisan optimize:clear in your local loop and an explicit cache invalidation in the definition's saved/deleted model events.
• Deleting a definition is a data-destruction decision, not a UI one. Prefer soft deletes plus a "hide" flag. Hard-deleting a definition typically leaves orphaned value rows (or, worse with JSON storage, leaves the key inside the blob and silently shows up in exports). Decide up front whether deletion cascades, archives, or blocks when values exist.
• JSON storage limits what you can query. where('custom_fields->vat_number', ...) works but is unindexable on most drivers; MySQL/Postgres generated columns or functional indexes are the escape hatch. If you anticipate filtering or sorting in list views on a custom field, know that constraint before you let users create fifty of them.
• Types are lossy. Everything through a JSON column tends to come back as a string. Cast on read according to the definition ((bool), (float), Carbon for dates) or you'll get "0" being truthy in Blade and null vs '' inconsistencies between UI save and seeder insert.
• Unique constraints are effectively unavailable. You cannot enforce uniqueness across a JSON key with a DB index. If a field needs uniqueness, that's a signal it should be a real column — don't fight the package.
• Migration ordering with published migrations. If you publish and then later update the package, its own new migrations won't run automatically if you've taken ownership of the migrations directory. Track upstream releases and diff database/migrations manually.
• Testing. Use RefreshDatabase and seed the definitions your tests need via a dedicated test seeder rather than the admin UI. Filament resource tests need the panel registered; test the rendering of a custom field once, then test business logic through the trait instead of re-rendering forms everywhere.
• Labels vs. codes in translations. Store labels in the DB but render through __() where the definition has a translation key. Mixing the two produces fields that are half-translated depending on where the user looks.
• Extension points to favour: the config's field-type map (add a custom type rather than abusing an existing one), model events on the definition model (invalidate caches, sync permissions), and a dedicated service class for building Filament components (so a future UI change is one file).
• Pin the version. At ~10 stars and a 0.x-style API surface, breaking changes are plausible between minor releases. Constrain the version in composer.json and read the diff before upgrading — particularly on the migrations and the morph/entity key format.
• Debugging checklist when a field "doesn't save": (1) is the definition active and attached to the right entity key? (2) is the form schema actually including it (cache)? (3) is the field present in the model's $fillable/handled by the trait, or is it being silently dropped by mass assignment? (4) does the value row exist after save but fail to hydrate on reload — that points at a morph map or cast problem, not a persistence one.