Nova Unique Ajax Field Laravel Package

Getting Started

This package provides a Laravel Nova field that validates a column's uniqueness via AJAX while the user types, instead of waiting for form submission. Version 1.0.2 is a breaking rename: the field class is now Unique (previously UniqueAjax).

1. Install and upgrade:

   composer require <vendor>/<package>:"^1.0.2"
   

2. Look first at:

   • The package README for install/publish steps.
   • The field class (Unique) and its service provider.
   • Any published config file for route/middleware/validation settings.
   • Your existing Nova resources for UniqueAjax references if upgrading from ≤1.0.1.

3. First use case — replace a standard Nova text field on a resource:

   use Vendor\Package\Fields\Unique;
   
   public function fields(NovaRequest $request)
   {
       return [
           Unique::make('Email')
               ->rules('required', 'email'),
       ];
   }
   

4. Confirm the AJAX check works in the Nova UI by typing a value that already exists in the underlying table. You should see inline feedback before saving.

Implementation Patterns

Basic uniqueness checking Use the field anywhere you would use Text, Email, or another single-column field. The field handles the AJAX lookup and Nova form integration.

Unique::make('Username')
    ->rules('required', 'alpha_dash', 'min:3')

Ignore the current model on update Uniqueness checks on edit forms must exclude the record being edited. Most implementations do this automatically via Nova's resource/model resolution, but verify against your package version and configure the ignored primary key if necessary.

Custom table/column mapping When the field name does not match the database column, set the column explicitly:

Unique::make('Display Email', 'email')
    ->rules('required', 'email')

Scoped uniqueness (multi-tenant or composite constraints) If uniqueness is only required within a tenant, parent record, or another scope, use Nova's validation rules on submit and consider the package's field-level options for scope/where clauses. Do not assume the AJAX check knows about your application's tenancy scope unless configured.

Pair with server-side rules Treat the AJAX field as UX enhancement, not a replacement for backend validation:

Unique::make('Email')
    ->rules('required', 'email', Rule::unique('users', 'email')->ignore($this->user))

This protects against race conditions, direct API writes, and disabled JavaScript.

Reuse across resources Create a small helper or base resource method if many resources use the same field configuration:

protected function uniqueEmailField()
{
    return Unique::make('Email')
        ->rules('required', 'email');
}

Testing Feature tests should assert the underlying validation rules, not the AJAX UI. For browser tests, assert that the field renders and that Nova's AJAX endpoint responds appropriately when authenticated.

Gotchas and Tips

• The 1.0.2 rename is breaking. Search the entire codebase for UniqueAjax and replace it with Unique, including use statements, field instantiations, config files, cached files, and tests. A global search-and-replace is usually sufficient, but check for string references in config or dynamically constructed class names.
• Clear caches after upgrading. Run php artisan optimize:clear and, if applicable, rebuild Nova assets. Stale compiled views or config caches can leave references to the old class.
• Do not rely solely on the AJAX check. The browser check can be bypassed or race with concurrent writes. Always keep a Rule::unique(...) or equivalent server-side rule.
• Watch for update-form false positives. If editing a record reports its own existing value as a duplicate, the field is not ignoring the current model ID. Check the package's ignore/primary-key configuration and your resource's model resolution.
• Soft deletes and scopes can surprise you. The AJAX query may not account for deleted_at, tenant IDs, or other global scopes unless configured. Verify the generated query or use a custom validation callback.
• Debug via the network tab first. If the inline check does not fire, inspect the AJAX request in browser devtools for 401/419/500 responses. Common causes are Nova middleware/auth issues, CSRF/session problems, or a missing route registration.
• Check case sensitivity and collation. MySQL collations may treat Foo and foo as duplicates while PostgreSQL does not. Confirm behavior matches your product requirements.
• Index the checked column. The AJAX check runs a query on each debounced keystroke. Ensure the underlying column is indexed, especially on large tables.
• Tune debounce/throttle if exposed. Aggressive per-keystroke checks can generate unnecessary load. If the package exposes timing options, set a sensible debounce.
• Pin versions in CI. Because 1.0.2 introduces a breaking rename, constrain to ^1.0.2 (or the appropriate range) and run the upgrade in a branch before merging.
• Extension points to inspect: field-level validation callbacks, configurable AJAX route/middleware, custom column/table resolution, and message customization. These are the safest places to adapt behavior without forking the package.