Download the PHP package milenmk/laravel-email-change-confirmation without Composer

Laravel Email Change Confirmation

A Laravel package that provides secure email change confirmation functionality. When users attempt to change their email address, they must confirm the change via their current email address before the change takes effect.

Features

• 🔒 Secure email changes - Users must confirm via their current email
• 📧 Automatic email verification - Integrates with Laravel's email verification
• 🎯 Framework agnostic - Works with any Laravel starter kit or custom application
• ⚡ Livewire support - Built-in support for Livewire applications
• 🔧 Highly configurable - Customize every aspect of the package
• 🎨 Extensible - Override controllers, notifications, and services
• 🚀 Auto-detection - Automatically detects email changes using model observers
• 📱 Responsive emails - Beautiful, mobile-friendly confirmation emails

Installation

Requirements

• PHP 8.2 or higher
• Laravel 10.0 ~ 13.0
• User model must use the Notifiable trait

Install the package via Composer:

Publish and run the migrations:

Optionally, publish the configuration file:

Add the HasEmailChangeConfirmation trait to your user model

Security Configuration (Recommended)

For enhanced security, add a hash secret to your .env file:

Add the generated line to your .env file. This enables HMAC-based hashing instead of plain SHA-256 for better security.

Quick Start

1. Add the Trait to Your User Model

Add the HasEmailChangeConfirmation trait to your User model:

2. Ensure Your User Model Uses the Notifiable Trait

The package requires the Notifiable trait to send emails:

3. That's It!

The package will automatically detect email changes and handle the confirmation process. When a user tries to change their email:

1. The original email remains unchanged
2. A confirmation email is sent to the current email address
3. The user must click "Confirm" to complete the change
4. If the user implements MustVerifyEmail, a verification email is sent to the new address

Usage

Automatic Detection (Recommended)

By default, the package automatically detects email changes using model observers. Simply update the user's email as you normally would:

Manual Integration

If you prefer manual control, disable auto-detection in the config and use the service directly:

Displaying Pending Email Changes

When a user has a pending email change, you can display a notification with a cancel button:

Using the Service Class

Livewire Integration

The package provides seamless Livewire integration:

In your Blade template:

Configuration

The package is highly configurable. Here are the key configuration options:

Automatic Cleanup of Expired Requests

The package provides automatic cleanup of expired email change requests to prevent database bloat and security issues.

Manual Cleanup

You can manually clean up expired requests using the provided Artisan command:

Automatic Cleanup with Task Scheduling

To automatically clean up expired requests, add the command to your app/Console/Kernel.php:

Configuration

Configure cleanup behavior in your config file:

When expired requests are cleaned up, they are marked as denied with a denied_at timestamp, preserving the audit trail while preventing them from being used.

Customization

Extending the Controller

Create your own controller that extends the package controller:

Update your configuration:

Configuring Redirects

You can configure where users are redirected after email change actions:

If no redirect route is configured, the package will try common routes like dashboard, home, profile.show, or profile, and fall back to the root URL (/).

For the cancel action specifically, if no redirect is configured, it will use back() to return to the previous page.

Custom Notification

Create your own notification class:

Custom Service

Extend the service for custom business logic:

Working with Different Laravel Setups

Laravel Breeze

Works out of the box. Just add the trait to your User model.

Laravel Jetstream

Works with both Livewire and Inertia stacks. For Inertia, you'll need to handle the frontend notifications manually.

Laravel Fortify

The package integrates seamlessly with Fortify's profile update actions.

Custom Applications

The package is designed to work with any Laravel application structure. Use manual integration if auto-detection doesn't work for your setup.

Trait Methods

Service Methods

Model Methods

Security Features

• Signed URLs: All confirmation links use Laravel's signed URL feature
• HMAC Hash verification: Email addresses are hashed using HMAC-SHA256 for additional security
• Time-based expiration: Confirmation links expire after a configurable time
• User verification: Multiple layers of user identity verification
• Rate limiting: Configurable limits on pending email changes and requests per hour
• Domain blocking: Block disposable/temporary email domains
• Security logging: Comprehensive logging of security events for monitoring

Security Configuration

The package includes several security features that can be configured:

Hash Secret (Recommended)

Set EMAIL_CHANGE_HASH_SECRET in your .env file for enhanced security:

• Minimum length: 16 characters (32+ recommended)
• Maximum length: No limit (but 64 characters is sufficient)
• Allowed characters: Any printable ASCII characters, base64-encoded strings recommended
• Generation: Use php -r "echo base64_encode(random_bytes(32));" for a secure 44-character base64 string

Rate Limiting

• max_requests_per_hour: Limit email change requests per user (default: 5)
• Route-level throttling: Additional protection at the HTTP level

Domain Blocking

• blocked_domains: Array of domains to block (e.g., temporary email services)
• Case-insensitive matching

Expiration Settings

• confirmation_email_expire_minutes: How long confirmation links remain valid (default: 60, recommended: 30 or less)

Verification Steps

After installation, verify everything is working:

1. Check Database Tables

Ensure the email_changes table was created:

2. Test Email Change

1. Log into your application
2. Try to change your email address
3. Check that:
   • The email in the database doesn't change immediately
   • You receive a confirmation email at your current address
   • The email contains confirm and deny buttons

3. Test Confirmation Flow

1. Click the "Confirm" button in the email
2. Verify that:
   • Your email address is updated in the database
   • If you implement MustVerifyEmail, you receive a verification email at the new address
   • You're redirected to the appropriate page

4. Test Denial Flow

1. Request another email change
2. Click the "Deny" button in the email
3. Verify that:
   • The email change is marked as denied
   • Your original email address remains unchanged
   • You're redirected to the appropriate page

Troubleshooting

Issue: Emails Not Sending

Solution:

1. Check your mail configuration in .env

2. Test mail sending with php artisan tinker:

3. Check your application logs for mail errors

Issue: User Model Doesn't Have Notifiable Trait

Error: User model must use the Notifiable trait

Solution: Add the Notifiable trait to your User model:

Issue: Auto-Detection Not Working

Solution:

1. Ensure the HasEmailChangeConfirmation trait is added to your User model
2. Check that auto_detect_email_changes is true in config
3. If still not working, try manual integration

Issue: Routes Not Working

Solution:

1. Clear route cache: php artisan route:clear
2. Check that routes are registered: php artisan route:list | grep email-change
3. Ensure middleware configuration is correct

Issue: Migration Fails

Solution:

1. Check if you have existing email_changes table
2. If using UUIDs for users, ensure the migration handles this correctly
3. Check database connection and permissions

Contributing

Please see CONTRIBUTING.md for details.

Security

See SECURITY.md for more information on how to report security vulnerabilities.

Credits

• Milen MK
• All Contributors

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Support My Work

If this package saves you time, you can support ongoing development:
👉 Become a Patron

Other Packages

Check out my other Laravel packages:

• Laravel GDPR Cookie Manager - GDPR-compliant cookie consent management with user preference tracking
• Laravel Blacklist - A Laravel package for blacklist validation of user input
• Laravel GDPR Exporter - GDPR-compliant data export functionality
• Laravel Locations - Add Countries, Cities, Areas, Languages and Currencies models to your Laravel application
• Laravel Rate Limiting - Advanced rate limiting capabilities with exponential backoff
• Laravel Datatables and Forms - Easy to use package to create datatables and forms for Livewire components

License

This package is licensed under the MIT License. See the LICENSE file for more details.

Disclaimer

This package is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or noninfringement.

The author(s) make no guarantees regarding the accuracy, reliability, or completeness of the code, and shall not be held liable for any damages or losses arising from its use.

Please ensure you thoroughly test this package in your environment before deploying it to production.