Merge pull request #36 from taylornetwork/dev

Version 2.5

.gitignore

@@ -2,3 +2,5 @@ vendor/
 composer.lock
 .idea/
 .phpunit.result.cache
+vendor
+vendor.nosync

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 TaylorNetwork
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -22,12 +22,22 @@ Easily generate unique usernames for a Laravel User Model
     - [Upper Case](#upper-case)
     - [Mixed Case](#mixed-case)
     - [Minimum Length](#minimum-length)
+    - [Maximum Length](#maximum-length)
 7. [Drivers](#drivers)
     - [Extending](#extending)
 8. [License](#license)
 
 ## Changes
 
+**v2.5**
+
+- Added maximum length check.
+- Added ability for pre-filled usernames to go through generate process to allow for consistent username styles.
+- Added checking for similar usernames using REGEXP or LIKE (LIKE is a fallback if REGEXP fails).
+- Added a check if a username is unique as is before checking for similar ones.
+- Updated `composer.json` to support PHP 7.2 and above
+- Updated readme for better Laravel 8+ quickstart
+
 **v2.4**
 
 - This is a minor change but if you're using older versions of Laravel you may need to update your config file.
@@ -69,40 +79,102 @@ Via Composer
 $ composer require taylornetwork/laravel-username-generator
 ```
 
-## Set Up
+### Publish Config
 
-Add the `FindSimilarUsernames` trait on your user model (or whichever model you want to use).
+This will add the config to `config/username_generator.php`
 
-```php
 
-// app/User.php
+```bash
+$ php artisan vendor:publish --provider="TaylorNetwork\UsernameGenerator\ServiceProvider"
+```
+
+## 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**
 
-namespace App;
+In `App\Models\User` (or `App\User` for Laravel 7) add the `FindSimilarUsernames` and `GeneratesUsernames` traits. 
+Add `'username'` to the fillable property.
 
-use Illuminate\Notifications\Notifiable;
-use Illuminate\Foundation\Auth\User as Authenticatable;
+```php
+
+// ...
 use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;
+use TaylorNetwork\UsernameGenerator\GeneratesUsernames;
 
 class User extends Authenticatable
 {
-    use Notifiable, FindSimilarUsernames;
+	// ...
+	use FindSimilarUsernames;
+	use GeneratesUsernames;
+
+	protected $fillable = [
+		// ...
+		'username',
+	];
+
+	// ...
 
-    // --
+}
+```
 
-}    
+**Database Migration**
+
+In your `database/2014_10_12_000000_create_users_table` add a username column.
+
+```php
+class CreateUsersTable extends Migration
+{
+    public function up()
+    {
+        Schema::create('users', function (Blueprint $table) {
+            // ...
+            $table->string('username')->unique();
+            // ...
+        });
+    }
+}
 ```
 
-### Laravel 7 and below
 
-If you're using Laravel 7 or below you'll need to publish the config using 
+### 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
 
 ```bash
-$ php artisan vendor:publish --provider="TaylorNetwork\UsernameGenerator\ServiceProvider"
+$ php artisan vendor:publish --tag=fortify-config
+```
+
+In the `config/fortify.php` change the `'username' => 'email'` to `'username' => 'username'`
+
+```php
+// ...
+
+'username' => 'username',
+
+'email' => 'email',
+
+// ... 
+```
+
+Update the login view in `resources/views/auth/login.blade.php` and replace Email with Username.
+
+```html
+<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 />
 ```
 
-And update your `config/username_generator.php` file to match your User model namespace (`App\User`).
 
-### Use username to login
+### 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`
 
@@ -113,11 +185,27 @@ public function username()
 }
 ```
 
-See Username Customization in [Laravel Authentication Docs](https://laravel.com/docs/5.8/authentication#included-authenticating)
+
+## Set Up
+
+Add the `FindSimilarUsernames` trait on your user model (or whichever model you want to use). 
+
+```php
+use TaylorNetwork\UsernameGenerator\FindSimilarUsernames;
+
+class User extends Authenticatable
+{
+    use FindSimilarUsernames;
+}    
+```
+
+**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**
+
 By default the `Generator` class has the following configuration:
 
 | Config | Value | Type |
@@ -126,7 +214,7 @@ By default the `Generator` class has the following configuration:
 | Separator | `''` | string (should be single character) |
 | Case | `'lower'` | string (one of lower, upper, or mixed) |
 | Username DB Column | `'username'` | string |
-| Class | `'\App\User'` | string |
+| Class | `'\App\Models\User'` | string |
 
 The config is stored in `config/username_generator.php`
 
@@ -137,8 +225,6 @@ You can override config on a new instance by `new Generator([ 'unique' => false
 #### generate($name)
 Create a new instance and call `generate($name)`
 
-*Note: This has replaced, the old `makeUsername` method which ~~is deprecated but still currently has support~~ no longer has support (as of v2.0)*
-
 ```php
 use TaylorNetwork\UsernameGenerator\Generator;
 
@@ -365,6 +451,42 @@ UsernameGenerator::generate('test');
 
 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` 
+
+```php
+'max_length' => 6,
+```
+
+By default if the generator generates a username more than the minimum 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
+
+```php
+
+UsernameGenerator::generate('test user');
+
+'testus' 
+
+```
+
+**Alternatively you can throw an exception when the maximum length has been exceeded**
+
+In `config/username_generator.php` set
+
+```php
+'throw_exception_on_too_long' => true,
+```
+
+```php
+UsernameGenerator::generate('test user');
+```
+
+Would throw a `UsernameTooLongException`
+
+
 ## Drivers
 
 2 drivers are included, `NameDriver` (default) and `EmailDriver`

composer.json

@@ -2,7 +2,7 @@
     "name": "taylornetwork/laravel-username-generator",
     "require": {
         "illuminate/support": ">=5.5",
-        "php": ">=7.1"
+        "php": "^7.2|^7.3|^7.4|^8.0"
     },
     "require-dev": {
         "orchestra/testbench": "^3.5",