Download the PHP package taylornetwork/laravel-username-generator without Composer
On this page you can find all versions of the php package taylornetwork/laravel-username-generator. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package laravel-username-generator
Laravel Username Generator
Easily generate unique usernames for a Laravel User Model.
Works for Laravel versions above 5.5 including Laravel 9.
- Change Log
- Install
- Set Up
- Config
- Allowed Characters
- Basic Usage
- generate($name)
- generateFor($model)
- GeneratesUsernames Trait
- UsernameGenerator Facade
- Other Examples
- With a Separator
- Upper Case
- Additional Casing Options
- Mixed Case
- Minimum Length
- Maximum Length
- Other Character Sets
- Drivers
- Extending
- License
Change Log
See the Change Log
Install
Via Composer
Publish Config
This will add the config to config/username_generator.php
Quickstart
This section will help you get up and running fast.
The following steps will be the same for all Laravel versions and assumes you're adding the package to a new installation.
User Model
In App\Models\User
(or App\User
for Laravel 7) add the FindSimilarUsernames
and GeneratesUsernames
traits.
Add 'username'
to the fillable property.
Database Migration
In your database/2014_10_12_000000_create_users_table
add a username column.
Laravel 8+
Note: if you are not using Laravel Jetstream for your project, simply continue with the Laravel 7 guide below.
Publish the Laravel Fortify config if you haven't already
In the config/fortify.php
change the 'username' => 'email'
to 'username' => 'username'
Update the login view in resources/views/auth/login.blade.php
and replace Email with Username.
Laravel 7 and below
In config/username_generator.php
update the User model namespace to match your project.
Using username to login
To use the username to login instead of the email you need to add the following to your LoginController
Set Up
Add the FindSimilarUsernames
trait on your user model (or whichever model you want to use).
Note: this is required in all cases if you want the username to be unique
Config
This is in the process of being updated on the wiki
See the default config
By default the Generator
class has the following configuration:
Config | Value | Type |
---|---|---|
Unique Username | true |
boolean |
Separator | '' |
string (should be single character) |
Case | 'lower' |
string (one of lower, upper, or mixed) |
Username DB Column | 'username' |
string |
Class | '\App\Models\User' |
string |
The config is stored in config/username_generator.php
You can override config on a new instance by new Generator([ 'unique' => false ]);
etc.
Allowed Characters
If you need to include additional characters beyond just 'A-Za-z'
you'll need to update the allowed_characters
config option.
You should also update 'convert_to_ascii'
to false
if you want the result to be in the same set.
For example
Please note that all characters not included in this list are removed before performing any operations. If you get an empty string returned double check that the characters used are included.
Basic Usage
generate($name)
Create a new instance and call generate($name)
Returns
If you do not provide a name to the generate method an adjective and noun will be chosen as the name at random, using noun and adjective word lists from alenoir/username-generator, which will then be converted to a username.
Returns something similar to
generateFor($model)
Create a new instance and call generateFor($model)
This will access the model's name
property and convert it to a username.
Returns
GeneratesUsernames Trait
This package also comes with a GeneratesUsernames
trait that you can add to your model and it will automatically call the username generator when the model is saving without the specified username column.
Note: you will also need to include the FindSimilarUsernames
trait either way
You can also add custom config to call before the username is generated.
Override the generatorConfig
method in your model
If you need to modify the data before handing it off to the generator, override the getField
method on your model.
For example if you have a first and last name rather than a single name field, you'll need to add this to your model.
Note: if your code still uses a custom getName
, it will still work, however it was replaced with getField
in v2.1 when driver support was added.
UsernameGenerator Facade
This package includes a UsernameGenerator
facade for easy access
Other Examples
With a Separator
Returns
Upper Case
Returns
Additional Casing Options
To change the casing, we make use of the Laravel String Helpers so any value that changes the case will work.
Studly (Pascal)
When using studly case the laravel helper will remove the spaces between separate words so if a separator is used it will be overridden. You would need to use title case (seen below) in order to have the same effect.
Title
This is the same as studly but the laravel helper will not remove spaces, so it can be used in conjunction with a separator
Ucfirst
Mixed Case
Returns
Note: Mixed case will just ignore changing case altogether
Returns
Note: if you pass an invalid value for the case
option, mixed case will be used.
Minimum Length
If you want to enforce a minimum length for usernames generated change the min_length
option in config/username_generator.php
By default if the generator generates a username less than the minimum length it will pad the end of it with a random digit between 0 and 9.
For example
Alternatively you can throw an exception when the minimum length has not been reached
In config/username_generator.php
set
Would throw a UsernameTooShortException
Maximum Length
If you want to enforce a maximum length for usernames generated change the max_length
option in config/username_generator.php
By default if the generator generates a username more than the maximum length it will cut it to the max length value and then try to make it unique again. If that becomes too long it will remove one character at a time until a unique username with the correct length has been generated.
For example
Alternatively you can throw an exception when the maximum length has been exceeded
In config/username_generator.php
set
Would throw a UsernameTooLongException
Other Character Sets
Any other character set can be used if it's encoded with UTF-8. You can either include by adding the set to the 'allowed_characters'
option.
Alternatively you can set 'validate_characters'
to false
to not check.
You will need to set 'convert_to_ascii'
to false
either way
Drivers
2 drivers are included, NameDriver
(default) and EmailDriver
To use a specific driver
OR
Extending
You can make your own custom drivers that extend TaylorNetwork\UsernameGenerator\Drivers\BaseDriver
or override an existing one.
Custom drivers require a public $field
property to be set which is the name of the field on the model to use to generate the username.
Drivers will perform the following operations in order:
In your custom driver you can add a method to perform an operation before or after any of the above operations.
Additionally if there is any operation you want to do as the very first or last thing you can use the first and last hooks.
Example
For example if you wanted to append -auto
to all automatically generated usernames, you could make a new driver in App\Drivers\AppendDriver
And then in config/username_generator.php
add the driver to the top of the drivers array to use it as default.
License
See the License