Download the PHP package willvincent/laravel-unique without Composer

Unique Names

A trait for Laravel Eloquent models to ensure a field remains unique within specified constraints.

It offers flexible suffix formats or custom value generators, making it ideal for scenarios like unique names, slugs, or identifiers.

How It Works

The HasUniqueNames trait hooks into the Laravel Eloquent saving event, which fires before a model is persisted to the database (on both create and update operations). It checks if the designated unique field (e.g., name) already exists within the defined constraints (e.g., organization_id). If a duplicate is detected:

• On create, it generates a unique value.
• On update, it only adjusts the field if it has changed (i.e., if it’s “dirty”).

If a duplicate exists, the trait either appends a suffix (e.g., Foo (1)) or uses a custom generator to produce a unique value.

Features

• Enforces uniqueness at the application level before saving.
• Supports custom suffix formats (e.g., ({n}) or -{n}).
• Allows custom value generators for advanced uniqueness logic.
• Configurable via a config file or model properties.
• Handles constraints (e.g., uniqueness within a specific scope).

Installation

Install the package via Composer:

Publish the configuration file (optional) to customize defaults:

Here’s the default configuration file (config/unique_names.php):

Usage

Add the HasUniqueNames trait to your Eloquent model and optionally configure it:

Configuration Options

You can customize the trait’s behavior either in the config/unique_names.php file or by overriding properties in your model:

• uniqueField: The field to enforce uniqueness on (default: 'name').
• constraintFields: Array of fields defining the uniqueness scope (default: []).
• uniqueSuffixFormat: Format for suffixes, with {n} as the number placeholder (default: ' ({n})').
• uniqueValueGenerator: Optional custom generator (see below).

Model properties take precedence over config file settings.

Examples

Default Suffix

Ensure names are unique within an organization:

• Input: name: "Foo", organization_id: 1
  • Output: "Foo" (if unique)
  • Output: "Foo (1)" (if "Foo" exists)
  • Output: "Foo (2)" (if "Foo" and "Foo (1)" exist)

Slug Format

Use a slug-friendly suffix:

• Input: slug: "bar", organization_id: 1
  • Output: "bar" (if unique)
  • Output: "bar-1" (if "bar" exists)

Custom Generator

Define a custom method or callable for unique values:

Method on Model:

Callable:

• Input: name: "baz"
  • Output: "baz-abc12" (random 5-character suffix)

The generator receives the base value, constraint values, and the retry attempt, and must return a unique string. It retries up to max_tries times if the generated value isn’t unique, the first attempt will be 0, retries will be numbered 1 through your limit.

Advanced Configuration

Custom Generator Details

The custom generator can be:

• A string: The name of a method on the model.
• A callable: An anonymous function or closure.

If the generated value isn’t unique, the trait retries with increasing attempt counts until max_tries is reached, then throws an exception.

Database Considerations

The trait enforces uniqueness at the application level. For data integrity, especially in high-concurrency scenarios, consider adding database-level unique constraints (e.g., unique indexes) alongside this trait.

Testing

The package includes a test suite with over 97% coverage of the code, testing:

• Uniqueness on create and update
• Suffix formats
• Custom generators
• Constraint handling
• Edge cases (e.g., null constraints, max tries)

Run the tests with:

Source Code

View or contribute to the package on GitHub: willvincent/laravel-unique

Changelog

See CHANGELOG for recent updates.

Credits

• Will Vincent
• All Contributors

License

MIT License. See LICENSE for more information.