Laravel Custom Fields Laravel Package

Getting Started

• composer require plin-code/laravel-custom-fields, then publish and run the package migrations (php artisan vendor:publish --tag=... and php artisan migrate). Check the published config/custom-fields.php for table names, value column types, and any caching settings before you build on top of it.
• First places to read: the migration that creates the field-definition and value tables (it tells you the uniqueness constraints the package relies on), the trait you add to your Eloquent models, and the filter classes (number, boolean, contains, etc.) used for querying.
• Minimal first use case: add the trait to one model, seed two or three field definitions (a number, a boolean, a contains text field), store values on a model, then expose a filtered index endpoint using the package's filters. This exercises definition lookup, storage, and querying in one pass.
• Validate the filter path early with a request test: a valid value returns 200, an invalid one now returns 400 (InvalidFilterValueException) rather than silently matching the wrong rows.

Implementation Patterns

• Treat field definitions as data, not code. Seed them per environment, cache the definition map (it is read on nearly every request), and clear that cache whenever a definition is created, renamed, or retyped. Keep a key/slug column you can reference from code so definitions can be renamed without breaking callers.
• Eager load values. When listing models with their custom fields, with() the values relation; a per-row lazy load of custom fields is the most common N+1 source in this kind of package.
• Filter at the HTTP boundary. Map query-string parameters to filter classes in a form request or a dedicated query object, and let InvalidFilterValueException bubble up as a 400. That keeps controller code thin and gives you one place to log rejected filter input.
• Rely on the unique index, not on exists() checks. The 1.0.1 fix wraps the insert in a savepoint and, on UniqueConstraintViolationException, turns the losing insert into an update of the row the other request wrote — later write wins, same as sequential execution. So write paths can be a plain "store value" call; do not add your own check-then-insert guard around it.
• Keep the unique index in your own migrations if you add scoping. For multi-tenant or per-user fields, the index must include the scope columns (e.g. tenant_id, field_id), otherwise the package's race handling resolves against the wrong row.
• Use it for import/upsert jobs too. Chunked imports that write the same field for the same record from parallel workers are exactly the scenario the savepoint fix covers; keep chunks small and treat the operation as last-write-wins.
• Testing. Assert the 400 path with a data provider over bad values (true, false, "1.5", arrays, empty string) and assert stored values round-trip through the filters. For concurrency, a paratest or a simulated double-insert inside a transaction is usually enough to confirm the savepoint behaviour.

Gotchas and Tips

• Booleans leaking into number filters. true/false in a query string are converted to PHP booleans before Laravel's integer rule sees them, and integer accepts booleans — previously that meant a number filter silently matched value 1, and contains searched for the literal 1. Both now throw InvalidFilterValueException. If your frontend sends ?count=true for a numeric field, it will start returning 400s; send the correct filter type or omit the parameter.
• Boolean filters are unaffected. ?active=true on a boolean filter still works as before — don't "fix" your frontend by converting booleans to 1/0, that just moves the bug.
• Map the exception to a response. If you don't already convert InvalidFilterValueException to 400, do it in the exception handler (render/register) so API consumers get a clean error instead of a 500.
• Last-write-wins is now guaranteed, not ordered. Two simultaneous writes to the same unique field leave the later one's value in place, but "later" is decided by whoever commits second. If your domain needs first-write-wins or conflict detection, add a version/updated_at guard yourself — the package will not surface a conflict.
• The fix depends on the unique index existing. If the index was dropped, renamed, or never created in a legacy environment, the savepoint path never triggers and you are back to silent duplicate/overwrite behaviour. Verify with your database's index listing after deploy.
• Nested transactions. The savepoint only helps inside a transaction. If you catch exceptions around the store call and continue, make sure you are not swallowing a rolled-back outer transaction; let the package's handling complete before doing more work.
• Upgrade is low-risk. No migration and no config change in 1.0.1 — composer update plin-code/laravel-custom-fields, then run your suite paying attention to filter tests and any endpoint that accepted loosely typed numbers.
• Debugging tips. Log the filter class name plus the raw (pre-cast) value when a 400 is raised; the exception message alone can be ambiguous about which parameter failed. For unique-field issues, temporarily log both the insert and the take-over update to confirm the savepoint path is the one running.