Laravel Custom Fields Laravel Package

Technical Evaluation

Architecture fit

• asseco-voice/laravel-custom-fields is a conventional Laravel package: service provider with auto-discovery, publishable config and migrations, and a trait applied to Eloquent models to expose custom field definitions and values. This is a standard, low-friction fit for an existing Laravel codebase and does not require architectural change.
• The underlying pattern is EAV (entity–attribute–value): field definitions live in a custom_fields table, values in a companion table keyed to the owning model. This is appropriate for sparse, admin-defined metadata; it is a poor fit for fields that need heavy filtering, sorting, or reporting.
• The v3.3.1 change adds a renderer column to custom_fields. Architecturally this moves presentation metadata (how a field should be drawn in a UI) into the persistence layer. That is pragmatic — it lets one definition drive consistent rendering across admin and consumer surfaces — but it couples the data model to a front-end concern and will need a documented contract (allowed renderer keys, fallback behaviour) rather than free-text.

Integration feasibility

• Installation is a composer require, migration publish, and trait addition on the target models. A mid-level Laravel developer can complete a first vertical slice in under a day.
• The added column is additive and, based on the release note, should be nullable/defaulted, so existing field definitions remain readable. No backfill is strictly required for the package to function; a backfill is only needed if rendering logic assumes a non-null renderer.

Technical risk

• Schema change in a patch release. v3.3.1 is a patch (3.3.0 → 3.3.1) that alters table structure. Semver-legal, but it means a routine composer update can require a database migration. Any environment that auto-deploys dependencies without running migrations will break at runtime, not at deploy time.
• Published-migration drift. If the project published the package migrations into database/migrations (the common case), the new column will not arrive automatically. The team must generate a project-owned migration adding the column. This is the single most likely failure mode of this upgrade and is not called out in the release note.
• Single-maintainer, low-cadence dependency. The package appears maintained by a small team with occasional releases. It is a real but manageable supply-chain and bus-factor risk for a component holding business-critical metadata.
• Assessment confidence. This evaluation is based on the v3.3.1 release note alone; no prior assessment or repository data was available. Version support matrix, test coverage, and the renderer contract are unverified.

Key questions

1. Which Laravel and PHP versions does v3.3.1 support, and is that matrix enforced in CI?
2. Is the renderer column nullable with a default, and what happens in code when it is null or holds an unrecognised value?
3. Are migrations loaded from the package or expected to be published? Is there a documented upgrade step for existing installs?
4. Does renderer participate in validation, casting, or field-type resolution — i.e. can a bad value break form rendering or data writes?
5. Is there an index strategy for values (model_type/model_id, field key) and is eager loading supported to avoid N+1?
6. What is the deletion/cleanup behaviour for values when the owning model is deleted?

Integration Approach

Stack fit

• Fits any Laravel + Eloquent stack on MySQL, PostgreSQL, or SQLite. Rendering is agnostic: the renderer value is metadata that a Blade, Livewire, Inertia/Vue, or API-driven front end can interpret.
• No queue, cache, or external service dependency is introduced. It is a pure database-backed component, which keeps the operational surface small.

Migration path

• Treat this as an additive, forward-only change. Recommended path for existing installs:
  1. Pin or bump to ^3.3.1 explicitly rather than floating on ^3.0.
  2. Diff the package's migration directory against the project's published migrations before deploying.
  3. Add a project-owned migration for the renderer column if migrations were published; if the package loads its own migrations, confirm the new file is picked up.
  4. Deploy migration and code together — do not deploy the dependency bump ahead of the migration.
• For new installs, publish and run as normal; verify the published custom_fields migration already includes renderer so no second migration is needed.

Compatibility

• Patch-level bump: no breaking API change is implied, and the column is additive. Existing definitions remain valid.
• The only compatibility question is behavioural: any project code that does SELECT-by-column-list or builds field definitions into a rigid DTO may need to tolerate the new attribute.

Sequencing

1. Upgrade dependency in a branch; run the full test suite against the new schema.
2. Add/adjust the migration; run against a production-shaped database copy to confirm it is non-locking and fast.
3. Define and document the renderer contract (enumerated keys + fallback) before exposing it in any admin UI.
4. Backfill renderer values for existing field definitions only if downstream rendering requires it.
5. Ship migration + code atomically, then regression-test custom field capture and display end to end.

Operational Impact

Maintenance

• Low ongoing effort: no services to run, no config to tune. The recurring cost is version tracking of a small OSS dependency and ownership of the published migrations.
• Because patch releases can carry schema changes, dependency updates for this package should not be fully automated. Route them through the normal review path, or at minimum gate Dependabot/Renovate PRs on a migration check.

Support

• Community-supported OSS with no SLA and a small maintainer group. Internal ownership must be assigned: someone accountable for upgrades, for the renderer contract, and for the decision to vendor/fork if upstream stalls.
• Pin the version in composer.json and commit composer.lock; avoid dev-main on a component holding business metadata.

Scaling

• EAV scales acceptably for read-mostly metadata displayed alongside records, which is the typical use case.
• Filtering, sorting, or reporting on custom field values requires joins per field and does not scale gracefully. If requirements grow toward "search and segment by custom field," plan a denormalised projection rather than pushing on the EAV tables.
• Ensure the values table is indexed on the owning model and field key, and that consumers eager-load values to avoid N+1 when listing records.

Failure modes

• Migration not applied: runtime SQL error on any query selecting renderer. Highest-probability failure; mitigated by atomic migration+code deploys.
• Published migrations not updated: silent — the package works but the column never exists until code paths reference it.
• Unknown or null renderer: UI renders the wrong control or nothing. Needs an explicit default/fallback.
• Renderer keys drifting: free-text values set by admins or scripts become an undeclared enum; validate on write.
• Orphaned values: deleting an owning model may leave value rows behind. Confirm cascade or observer behaviour before this data becomes business-critical.
• Upstream abandonment: low likelihood but high impact if field definitions proliferate; keep an exit plan (values are plain rows, so extraction is feasible).

Ramp-up

• Minimal. Any Laravel developer familiar with Eloquent traits can adopt, extend, and debug this package. Budget roughly one day for a first integration and half a day of team onboarding on the EAV model and the renderer contract.
• The knowledge worth documenting internally is not the package API but the two project-specific decisions: how migrations are managed, and what the renderer keys mean.