Feature: Unique key

[pxlrbt]

What is the reason for this PR?

• A new feature
• Fixed an issue (resolve #ID)

Author's checklist

• Follow the Contribution Guide
• New features and changes are documented

Summary of changes

When using FakerPHP in database factories, such as in Laravel, I frequently encounter the need for unique values for a specific model or column. For example, unique emails for that model or a non-auto-incrementing ID that needs to be set.

Consider this implementation of a Laravel database factory:

class UserFactory extends Factory
{
    public function definition(): array
    {
        return [
            'external_id' => $this->faker->unique()->numberBetween(0, 99),
        ];
    }
}

Because of the ->unique() method, we obtain a unique external_id for each user. However, we may have another model that also requires unique numbers. Ideally, the IDs should be reset for this model. However, calling ->unique(reset: true) would reset the entire generator, causing it to reset on every call.

class EmployeeFactory extends Factory
{
    public function definition(): array
    {
        return [
            'external_id' => $this->faker->unique(reset: true)->numberBetween(0, 99),
        ];
    }
}

Therefore, I propose an option to add a key so that people can have multiple unique generators. This would allow us to have an independent set of unique numbers for both factories and models.

class UserFactory extends Factory
{
    public function definition(): array
    {
        return [
            'external_id' => $this->faker->unique(key: 'user.external_id')->numberBetween(0, 99),
        ];
    }
}

class EmployeeFactory extends Factory
{
    public function definition(): array
    {
        return [
            'external_id' => $this->faker->unique(key: 'employee.external_id')->numberBetween(0, 99),
        ];
    }
}

What do you think about this?

I'm not sure whether you consider $uniqueGenerator internal or if removing $uniqueGenerator and adding $uniqueGenerators is considered a breaking change.

Maybe this should be implemented as a new method, but I couldn't think of a better name than keyedUnique(). It appears that there is some confusion surrounding the usage of ->unique() in general.

laravel/framework#46287
laravel/laravel#5137

Review checklist

• All checks have passed
• Changes are added to the CHANGELOG.md
• Changes are approved by maintainer

[pxlrbt]

For now, I have created a small package that adds a betterUnique() method that allows a key as first param:
https://github.com/pxlrbt/faker-better-unique

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 1 week if no further activity occurs. Thank you for your contributions.

[pxlrbt]

"Activity" 🤖

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 1 week if no further activity occurs. Thank you for your contributions.

[ulcuber]

I think we could also pass &$uniques = [] to init generator

[pxlrbt]

Sorry, I can't follow.

[ulcuber]

I've tried this

Provider

$this->app->singleton('faker.unique.users.email', function ($app) {
    $uniques = User::pluck('email')->all();
    return new UniqueGenerator(fake(), 10000, $uniques);
});

Factory

'email' => app('faker.unique.users.email')->safeEmail(),

Still not enough for paratest to fully avoid database exceptions for unique keys
But at least it could help to split by keys to prevent OverflowException