README

为Laravel User Model轻松生成唯一用户名。

适用于5.5以上版本的Laravel，包括Laravel 9。

变更日志
安装
设置
配置
- 允许字符
基本用法
其他示例
驱动器
- 扩展
许可

变更日志

安装

通过Composer

$ composer require taylornetwork/laravel-username-generator

发布配置

这将在 config/username_generator.php 中添加配置

$ php artisan vendor:publish --provider="TaylorNetwork\UsernameGenerator\ServiceProvider"

快速入门

本节将帮助您快速启动。

以下步骤对所有Laravel版本相同，并假设您正在将包添加到新安装中。

用户模型

在 App\Models\User（或Laravel 7的App\User）中添加 FindSimilarUsernames 和 GeneratesUsernames 特性。将 'username' 添加到 fillable 属性。

// ...
use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;
use TaylorNetwork\UsernameGenerator\GeneratesUsernames;

class User extends Authenticatable
{
	// ...
	use FindSimilarUsernames;
	use GeneratesUsernames;
	
	protected $fillable = [
		// ...
		'username',
	];
	
	// ...

}

数据库迁移

在您的 database/2014_10_12_000000_create_users_table 中添加一个用户名列。

class CreateUsersTable extends Migration
{
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            // ...
            $table->string('username')->unique();
            // ...
        });
    }
}

Laravel 8+

注意：如果您在项目中未使用Laravel Jetstream，请继续按照下面的Laravel 7指南进行。

如果您尚未发布，请发布Laravel Fortify配置

$ php artisan vendor:publish --tag=fortify-config

在 config/fortify.php 中将 'username' => 'email' 更改为 'username' => 'username'

// ...

'username' => 'username',

'email' => 'email',
    
// ...

更新 resources/views/auth/login.blade.php 中的登录视图，并将电子邮件替换为用户名。

<x-jet-label for="email" value="{{ __('Username') }}" />
<x-jet-input id="email" class="block mt-1 w-full" type="text" name="username" :value="old('username')" required autofocus />

Laravel 7及以下

在 config/username_generator.php 中更新用户模型命名空间以匹配您的项目。

使用用户名登录

要使用用户名而不是电子邮件登录，您需要在您的 LoginController 中添加以下内容

public function username()
{
    return 'username';
}

设置

在用户模型（或您想要使用的任何模型）上添加 FindSimilarUsernames 特性。

use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;

class User extends Authenticatable
{
    use FindSimilarUsernames;
}

注意：如果您想要用户名是唯一的，则此操作在所有情况下都是必需的

配置

此过程正在wiki上更新

查看默认配置

默认情况下，Generator 类具有以下配置

配置存储在 config/username_generator.php

您可以通过 new Generator([ 'unique' => false ]); 等等来在新实例上覆盖配置。

允许字符

如果您需要包含除 'A-Za-z' 之外的其他字符，则需要更新 allowed_characters 配置选项。

如果您希望结果在同一组中，还应将 'convert_to_ascii' 更改为 false。

例如

   'allowed_characters' => 'А-Яа-яA-Za-z',   // Would also allow Cyrillic characters
   
   'allowed_characters' => 'А-Яа-яA-Za-z-_' // Includes Cyrillic, Latin characters as well as '-' and '_'
   
   'allowed_characters' => '\p{Cyrillic}\p{Greek}\p{Latin}\s ' // Includes cyrillic, greek and latin sets and all spaces

请注意，在执行任何操作之前，将删除此列表之外的所有字符。如果返回空字符串，请再次检查所使用的字符是否包含在此列表中。

基本用法

generate($name)

创建一个新的实例并调用 generate($name)

use TaylorNetwork\UsernameGenerator\Generator;

$generator = new Generator();

$username = $generator->generate('Test User');

'testuser'

如果您没有为generate方法提供名称，系统将随机选择一个形容词和名词作为名称，使用alenoir/username-generator中的名词和形容词列表，然后将它们转换为用户名。

use TaylorNetwork\UsernameGenerator\Facades\UsernameGenerator;

$username = UsernameGenerator::generate();

返回类似以下内容：

'monogamousswish'

generateFor($model)

创建一个新实例并调用generateFor($model)

这将访问模型的name属性并将其转换为用户名。

use TaylorNetwork\UsernameGenerator\Generator;

class User
{
	public $name = 'Some Other User';
	
	public function getUsername()
	{
		$generator = new Generator();
		return $generator->generateFor($this);
	}
}

'someotheruser'

GeneratesUsernames 特性

此包还包含一个GeneratesUsernames特质，您可以将它添加到您的模型中，当模型保存且未指定用户名列时，它将自动调用用户名生成器。

注意：无论如何，您还需要包含FindSimilarUsernames特质

use TaylorNetwork\UsernameGenerator\GeneratesUsernames;
use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;

class User 
{
	use FindSimilarUsernames, GeneratesUsernames;
}

您还可以添加自定义配置，在生成用户名之前调用。

覆盖您模型中的generatorConfig方法

use TaylorNetwork\UsernameGenerator\GeneratesUsernames;
use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;

class User 
{
	use FindSimilarUsernames, GeneratesUsernames;
	
	public function generatorConfig(&$generator) 
	{
		$generator->setConfig([ 'separator' => '_' ]);
	}
}

如果您需要在传递给生成器之前修改数据，请覆盖您模型上的getField方法。例如，如果您有一个包含姓氏和名字的单个字段，而不是单独的名字字段，您需要将其添加到您的模型中。

class User 
{
	// ...
	
	public function getField(): string
	{	
		return $this->first_name . ' ' . $this->last_name;
	}
	
	// ...
}

注意：如果您的代码仍然使用自定义的getName，它仍然会工作，但在v2.1中添加了驱动支持时，它已被getField替代。

UsernameGenerator 门面

此包包括一个UsernameGenerator外观，便于访问

UsernameGenerator::generate('Test User');

UsernameGenerator::generateFor($user);

UsernameGenerator::setConfig([ 'separator' => '_' ])->generate('Test User');

其他示例

使用分隔符

$generator = new Generator([ 'separator' => '_' ]);
$generator->generate('Some User');

some_user

大写

$generator = new Generator([ 'case' => 'upper' ]);
$generator->generate('Some User');

SOMEUSER

其他大小写选项

要更改大小写，我们使用Laravel字符串助手，因此任何更改大小写的值都将工作。

Studly（Pascal）

UsernameGenerator::setConfig([ 'case' => 'studly' ])->generate('test user');
// Returns 'TestUser'

当使用studly case时，laravel助手将删除单词之间的空格，因此如果使用分隔符，它将被覆盖。您需要使用标题大小写（见下文）才能达到相同的效果。

UsernameGenerator::setConfig([ 'case' => 'studly', 'separator' => '_' ])->generate('test user');
// Returns 'TestUser'

Title

这与studly相同，但laravel助手不会删除空格，因此它可以与分隔符一起使用。

UsernameGenerator::setConfig([ 'case' => 'title' ])->generate('test user');
// Returns 'TestUser'

UsernameGenerator::setConfig([ 'case' => 'title', 'separator' => '_' ])->generate('test user');
// Returns 'Test_User'

Ucfirst

UsernameGenerator::setConfig([ 'case' => 'ucfirst' ])->generate('test user');
// Returns 'Testuser'

混合大小写

$generator = new Generator([ 'case' => 'mixed' ]);
$generator->generate('Some User');

SomeUser

注意：混合大小写将完全忽略更改大小写。

$generator = new Generator([ 'case' => 'mixed' ]);
$generator->generate('SoMe WeIrD CapitaliZation');

SoMeWeIrDCapitaliZation

注意：如果传递了无效的case选项值，则将使用混合大小写。

最小长度

如果您想强制生成用户名的最小长度，请更改config/username_generator.php中的min_length选项

'min_length' => 6,

默认情况下，如果生成器生成的用户名小于最小长度，它将在末尾填充一个介于0到9之间的随机数字。

例如

UsernameGenerator::generate('test');

// Would return the following where 0 is a random digit

'test00'

或者，您可以在未达到最小长度时抛出异常

在config/username_generator.php中设置

'throw_exception_on_too_short' => true,

UsernameGenerator::generate('test');

将抛出UsernameTooShortException

最大长度

如果您想强制生成用户名的最大长度，请更改config/username_generator.php中的max_length选项

'max_length' => 6,

默认情况下，如果生成器生成的用户名超过最大长度，它将截断到最大长度值，然后尝试再次使其唯一。如果这仍然太长，它将逐个删除字符，直到生成具有正确长度的唯一用户名。

例如

UsernameGenerator::generate('test user');

'testus'

或者，您可以在超过最大长度时抛出异常

在config/username_generator.php中设置

'throw_exception_on_too_long' => true,

UsernameGenerator::generate('test user');

将抛出UsernameTooLongException

其他字符集

任何其他字符集都可以使用，如果它使用UTF-8编码。您可以通过将集合添加到'allowed_characters'选项中来包含它。

或者，您可以设置'validate_characters'为false以不进行检查。

无论如何，您都需要将'convert_to_ascii'设置为false

$generator = new Generator([
    'allowed_characters' => '\p{Greek}\p{Latin}\s ',
    'convert_to_ascii' => false,
]);

$generator->generate('Αυτό είναι ένα τεστ');

// Returns

'αυτόείναιένατεστ'

驱动器

包含2个驱动程序，NameDriver（默认）和EmailDriver

要使用特定驱动程序

UsernameGenerator::usingEmail()->generate('testuser@example.com');

// Returns

'testuser'

或者

$generator = new Generator();
$generator->setDriver('email');
$generator->generate('test.user77@example.com');

// Returns

'testuser'

扩展

您可以创建自己的自定义驱动程序，这些驱动程序扩展TaylorNetwork\UsernameGenerator\Drivers\BaseDriver或覆盖现有的一个。

自定义驱动需要设置一个 public $field 属性，该属性是用于生成用户名的模型字段名称。

驱动将按照以下顺序执行以下操作：

[
	'stripUnwantedCharacters',     // Removes all unwanted characters from the text
	'convertCase',                 // Converts the case of the field to the set value (upper, lower, mixed)
	'collapseWhitespace',          // Collapses any whitespace to a single space
	'addSeparator',                // Converts all spaces to separator
	'makeUnique',                  // Makes the username unique (if set)
]

在你的自定义驱动中，你可以添加一个方法来在上述任何操作之前或之后执行操作。

public function beforeConvertCase(string $text): string 
{

	// --
	
}

public function afterStripUnwantedCharacters(string $text): string 
{

	// --
	
}

此外，如果你想在非常开始或结束时执行某个操作，可以使用第一和最后一个钩子。

public function first(string $text): string 
{
    // Happens first before doing anything else
}

public function last(string $text): string 
{
    // Happens last just before returning
}

示例

例如，如果你想将 -auto 追加到所有自动生成的用户名中，你可以在 App\Drivers\AppendDriver 中创建一个新的驱动。

namespace App\Drivers;

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class AppendDriver extends BaseDriver
{	
    public $field = 'name';
    
    public function afterMakeUnique(string $text): string
    {
    	return $text . '-auto';
    }
}

然后在 config/username_generator.php 中将驱动添加到驱动数组的最顶部，以将其用作默认值。

'drivers' => [
	'append' => \App\Drivers\AppendDriver::class,
        ...
    ],

许可

请参阅许可协议

taylornetwork / laravel-username-generator

维护者

详细信息