Custom Drivers

You can create your own custom drivers easily by extending the BaseDriver class.

Creating the Driver Class

The only requirement that a driver class has is a public $field property that is the field name on the model to get the input from.

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class CustomDriver extends BaseDriver
{
	public $field = '[field name on model]';
}

Actions

All drivers will execute the following actions to transform the input into the username.

The order in which these are done by default is:

1. toAscii
2. stripUnwantedCharacters
3. convertCase
4. collapseWhitespace
5. addSeparator
6. makeUnique
7. checkMinLength
8. checkMaxLength

Convert to ASCII

Key: 'toAscii'

Converts input to ASCII string, if applicable.

Strip Unwanted Characters

Key: 'stripUnwantedCharacters'

Removes all characters from string not in 'allowed_characters' config setting.

Convert Case

Key: 'convertCase'

Converts the case to the 'case' config setting using Laravel String Helpers. If that fails, converting case is ignored.

Collapse Whitespace

Key: 'collapseWhitespace'

Converts all whitespace in input to single spaces, and removes whitespace from start and end.

Add Separators

Key: 'addSeparator'

Replaces all spaces with the 'separator' character in config.

Make Unique

Key: 'makeUnique'

Attempts to make the username unique.

Check Minimum Length

Key: 'checkMinLength'

Checks to see if the username length adheres to the 'min_length' value in config. Then will either pad digits or throw an exception depending on the value of 'throw_exception_on_too_short'.

Check Maximum Length

Key: 'checkMaxLength'

Checks to see if the username length adheres to the 'max_length' value in config. Then will either reduce the length or throw an exception depending on the value of 'throw_exception_on_too_long'.

Hooks

You may add a hook to any of the above actions in your driver class by prefixing either 'before' or 'after' to any of the action names. If there are any actions that are the very first or last things you may also add those methods.

First

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class CustomDriver extends BaseDriver
{
	public $field = '[field name on model]';

	public function first(string $text): string
	{
		return str_replace('*', ' ', $text);
	}
}

Will replace all * in the text with spaces and then perform username generation.

Last

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class CustomDriver extends BaseDriver
{
	public $field = '[field name on model]';

	public function last(string $text): string
	{
		return '*' . $text . '*';
	}
}

Will add * to the start and end of the generated username.

Before

If you want to modify the input before converting the case:

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class CustomDriver extends BaseDriver
{
	public $field = '[field name on model]';

	public function beforeConvertCase(string $text): string
	{
		return '123-' . $text;
	}
}

After

If you want to modify text after making it unique:

use TaylorNetwork\UsernameGenerator\Drivers\BaseDriver;

class CustomDriver extends BaseDriver
{
	public $field = '[field name on model]';

	public function beforeConvertCase(string $text): string
	{
		return '123-' . $text;
	}

	public function afterMakeUnique(string $text): string
	{
		return $text . '-auto';
	}
}

Registration

You must register your driver in config/username_generator.php in order to use it.

'drivers' => [
	// other drivers...
	'custom' => CustomDriver::class,
],

Note:

Whichever driver is the first item registered will be used as the default driver if none is specified.

Usage

You may now use your custom driver by either using the setDriver method or the using* static method.

UsernameGenerator::usingCustom()->generate('test');

(new Generator)->setDriver('custom')->generate('test');

---

Next (Method Reference)