README

This Laravel package provides a complete authentication solution with registration, login, password reset, and OpenAPI documentation, all ready to use out of the box.

Features

Ready-to-use authentication endpoints:
- Registration (first_name, last_name, email, phone)
- Login
- Password reset (forgot password, reset password)
OpenAPI documentation: Automatically generated documentation using PHP attributes.
Customizable user model: Includes phone field.
Verification interface: Enables custom verification logic (e.g., email verification).
Configuration file: Easily customize settings.
Laravel agnostic considerations: designed with future framework agnosticism in mind.

Installation

1. Require the package

composer require whilesmart/laravel-user-authentication

2. Publish the configuration and migrations:

You do not need to publish the migrations and configurations except if you want to make modifications. You can choose to publish the migrations, routes, controllers separately or all at once.

2.1 Publishing only the routes

Run the command below to publish only the routes.

php artisan vendor:publish --tag=laravel-user-authentication-routes
php artisan migrate

The routes will be available at routes/laravel-user-authentication.php. You should require this file in your api.php file.

    require 'laravel-user-authentication.php';

2.2 Publishing only the migrations

+If you would like to make changes to the migration files, run the command below to publish only the migrations.

php artisan vendor:publish --tag=laravel-user-authentication-migrations
php artisan migrate

The migrations will be available in the database/migrations folder.

2.3 Publish only the controllers

To publish the controllers, run the command below

php artisan vendor:publish --tag=laravel-user-authentication-controllers
php artisan migrate

The controllers will be available in the app/Http/Controllers/Api/Auth directory. Finally, change the namespace in the published controllers to your namespace.

Note: Publishing the controllers will also publish the routes. See section 2.1

2.4 Publish the config

To publish the config, run the command below

php artisan vendor:publish --tag=laravel-user-authentication-config

The config file will be available in the config/laravel-user-authentication.php. The config file has the folowing variables:

register_routes: Default true. Auto registers the routes. If you do not want to auto-register the routes, set the value to `false
route_prefix: Default api. Defines the prefix for the auto-registered routes.

2.5 Publish everything

To publish the migrations, config, routes, and controllers, you can run the command below

php artisan vendor:publish --tag=laravel-user-authentication
php artisan migrate

Note: See section 2.1 above to make the routes accessible

3. Updates to the User model

Add the following to the $fillable variable in your User model:

'first_name',
'last_name',
'username',
'phone'

5. Events Emitted

This package emits the following events:

UserRegisteredEvent: This event is emitted after a user successfully registers

UserRegisteredEvent::dispatch($user);

UserLoggedInEvent:: This event is emitted after a user successfully logs in

UserLoggedInEvent::dispatch($user);

UserLoggedOutEvent: This event is emitted after a user successfully logs out

UserLoggedOutEvent::dispatch($user);

PasswordResetCompleteEvent: This event is emitted after a user successfully reset their password

PasswordResetCompleteEvent::dispatch($user);

PasswordResetCodeGeneratedEvent: This event is emitted after a user requests to reset their password

PasswordResetCodeGeneratedEvent::dispatch($email, $verificationCode);

Usage

After installation, the following API endpoints will be available:

POST /api/register: Register a new user.
POST /api/login: Log in an existing user.
POST /api/logout: Logs out an existing user.
POST /api/password/forgot: Request a password reset.
POST /api/password/reset: Reset a password.
OpenAPI Documentation: Accessible via a route that your OpenAPI package defines.

Example Registration Request:

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email address removed]",
    "phone": "+15551234567",
    "password": "password123",
    "password_confirmation": "password123"
}

whilesmart / laravel-user-authentication

Maintainers

Details