mohammed-abd-razaq/laravel-phone-otp-auth

A professional Laravel package for phone-based authentication with OTP verification, following clean architecture principles and Laravel best practices.

1.0.0 2025-08-03 19:38 UTC

Requires

• php: ^8.0
• laravel/framework: ^9.0|^10.0|^11.0
• laravel/sanctum: ^3.0

Requires (Dev)

• mockery/mockery: ^1.0
• orchestra/testbench: ^7.0|^8.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Mohammed Abd Razaq

• api
• Authentication
• sms
• laravel
• otp
• clean-architecture
• password-reset
• phone-auth

README

A professional Laravel package for phone-based authentication with OTP verification, following clean architecture principles and Laravel best practices.

🚀 Features

• Phone-based Authentication - Login and register using phone numbers
• OTP Verification - Secure one-time password verification
• Password Reset - Phone-based password reset with OTP
• Clean Architecture - Repository pattern with service layer
• Laravel Standards - Follows Laravel package conventions
• Flexible Configuration - Customizable phone column and settings
• Multi-language Support - Built-in internationalization
• Professional Code - SOLID principles and clean code practices

📋 Requirements

• PHP 8.0+
• Laravel 9.0+
• Laravel Sanctum (for API tokens)

🔧 Installation

1. Install the Package

composer require mohammed-abd-razaq/laravel-phone-auth

2. Publish Configuration

php artisan vendor:publish --tag=auth-package-config

3. Run Migrations

php artisan migrate

4. Publish Language Files (Optional)

php artisan vendor:publish --tag=auth-package-lang

⚙️ Configuration

Environment Variables

Add these to your .env file:

AUTH_PHONE_COLUMN=phone
AUTH_USER_MODEL=App\Models\User

Configuration Options

Edit config/auth-package.php:

return [
    // Phone column name in users table
    'phone_column' => env('AUTH_PHONE_COLUMN', 'phone'),
    
    // User model class
    'user_model' => env('AUTH_USER_MODEL', 'App\Models\User'),
    
    // OTP settings
    'otp_length' => 6,
    'otp_expiration_minutes' => 30,
    'max_verify_attempts' => 3,
    'max_resend_count' => 3,
    'resend_delay_minutes' => 1,
    'verify_delay_minutes' => 1,
    'suspend_time_minutes' => 120,
];

🛣️ API Endpoints

Public Routes

Method	Endpoint	Description
POST	/api/auth/login	Login with phone and password
POST	/api/auth/register	Register new user
POST	/api/auth/request-password-reset	Request password reset
POST	/api/auth/verify-password-reset-otp	Verify password reset OTP
POST	/api/auth/resend-password-reset-otp	Resend password reset OTP

Protected Routes

Method	Endpoint	Description
POST	/api/auth/verify-otp	Verify signup OTP
POST	/api/auth/resend-otp	Resend signup OTP
POST	/api/auth/change-password	Change password
POST	/api/auth/logout	Logout user
GET	/api/auth/profile	Get user profile

📝 Usage Examples

Registration Flow

// 1. Register user (Public)
$response = $this->post('/api/auth/register', [
    'name' => 'John Doe',
    'phone' => '[phone]',
    'email' => '[e-mail]',
    'password' => 'password123',
]);

// 2. Verify OTP (Protected - requires token)
$response = $this->withToken($token)->post('/api/auth/verify-otp', [
    'otp' => '123456',
]);

Login Flow

// Login (Public)
$response = $this->post('/api/auth/login', [
    'phone' => '[phone]',
    'password' => 'password123',
]);

Password Reset Flow

// 1. Request password reset (Public)
$response = $this->post('/api/auth/request-password-reset', [
    'phone' => '[phone]',
]);

// 2. Verify password reset OTP (Public)
$response = $this->post('/api/auth/verify-password-reset-otp', [
    'phone' => '[phone]',
    'otp' => '123456',
]);

// 3. Change password (Protected - requires token)
$response = $this->withToken($token)->post('/api/auth/change-password', [
    'password' => 'newpassword123',
]);

🧪 Testing

The package includes comprehensive testing support:

• Unit Tests: Test individual components
• Feature Tests: Test complete workflows
• Integration Tests: Test API endpoints

Run tests with:

composer test

🔧 Customization

Custom Phone Column

If your users table uses a different column name:

AUTH_PHONE_COLUMN=mobile_number

Custom User Model

AUTH_USER_MODEL=App\Models\CustomUser

🛡️ Security Features

• OTP Expiration - OTPs expire after configurable time
• Rate Limiting - Prevents abuse of OTP requests
• Failed Attempt Tracking - Tracks and limits failed attempts
• Secure Token Management - Uses Laravel Sanctum
• Input Validation - Comprehensive request validation
• Phone Number Cleaning - Standardizes phone number format

🔄 Error Handling

The package provides consistent error responses:

{
    "success": false,
    "message": "Invalid phone number",
    "errors": {
        "phone": ["The phone number format is invalid"]
    }
}