protonemedia/laravel-verify-new-email

Package to handle email address updates and verification

v1.6.0 2022-03-24 20:22 UTC

README

Latest Version on Packagist run-tests Quality Score Total Downloads

Laravel supports verifying email addresses out of the box. This package adds support for verifying new email addresses. When a user updates its email address, it won't replace the old one until the new one is verified. Super easy to set up, still fully customizable. If you want it can be used as a drop-in replacement for the built-in Email Verification features as this package supports unauthenticated verification and auto-login. Support for Laravel 6.0 and higher and requires PHP 7.3 or higher.

Launcher 🚀

Hey! We've built a Docker-based deployment tool to launch apps and sites fully containerized. You can find all features and the roadmap on our website, and we are on Twitter as well!

Blogpost

If you want to know more about the background of this package, please read the blog post.

Support

We proudly support the community by developing Laravel packages and giving them away for free. Keeping track of issues and pull requests takes time, but we're happy to help! If this package saves you time or if you're relying on it professionally, please consider supporting the maintenance and development.

Requirements

  • PHP 7.4 or higher
  • Laravel 8 or higher

Installation

You can install the package via composer:

composer require protonemedia/laravel-verify-new-email

Configuration

Publish the database migration, config file and email view:

php artisan vendor:publish --provider="ProtoneMedia\LaravelVerifyNewEmail\ServiceProvider"

You can set the redirect path in the verify-new-email.php config file. The user will be redirected to this path after verification.

The expire time of the verification URLs can be changed by updating the auth.verification.expire setting and defaults to 60 minutes.

Usage

Add the MustVerifyNewEmail trait to your User model and make sure it implements the framework's MustVerifyEmail interface as well.

<?php

namespace App;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use ProtoneMedia\LaravelVerifyNewEmail\MustVerifyNewEmail;

class User extends Authenticatable implements MustVerifyEmail
{
    use MustVerifyNewEmail, Notifiable;
}

Now your User model has a few new methods:

// generates a token and sends a verification mail to 'me@newcompany.com'.
$user->newEmail('me@newcompany.com');

// returns the currently pending email address that needs to be verified.
$user->getPendingEmail();

// resends the verification mail for 'me@newcompany.com'.
$user->resendPendingEmailVerificationMail();

// deletes the pending email address
$user->clearPendingEmail();

The newEmail method doesn't update the user, its current email address stays current until the new one if verified. It stores a token (associated with the user and new email address) in the pending_user_emails table. Once the user verifies the email address by clicking the link in the mail, the user model will be updated and the token will be removed from the pending_user_emails table.

The resendPendingEmailVerificationMail does the same, it just grabs the new email address from the previous attempt.

Login after verification

The user that verified its email address will be logged in automatically. You can disable this by changing the login_after_verification configuration setting to false.

Overriding the default Laravel Email Verification

The default Laravel implementation requires the user to be logged in before it can verify its email address. If you want to use this package's logic to handle that first verification flow as well, override the sendEmailVerificationNotification method as shown below.

<?php

namespace App;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use ProtoneMedia\LaravelVerifyNewEmail\MustVerifyNewEmail;

class User extends Authenticatable implements MustVerifyEmail
{
    use MustVerifyNewEmail, Notifiable;

    public function sendEmailVerificationNotification()
    {
        $this->newEmail($this->getEmailForVerification());
    }
}

Customization

You can change the content of the verification mail by editing the published views which can be found in the resources/views/vendor/verify-new-email folder. The verifyNewEmail.blade.php view will be sent when verifying updated email addresses. The verifyFirstEmail.blade.php view will be sent when a User verifies its initial email address for the first time (after registering). Alternatively, you set your own custom Mailables classes in the config file:

<?php

return [

    'mailable_for_first_verification' => \ProtoneMedia\LaravelVerifyNewEmail\Mail\VerifyFirstEmail::class,

    'mailable_for_new_email' => \ProtoneMedia\LaravelVerifyNewEmail\Mail\VerifyNewEmail::class,

];

You can also override the sendPendingEmailVerificationMail method to change the behaviour of sending the verification mail:

<?php

namespace App;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use ProtoneMedia\LaravelVerifyNewEmail\MustVerifyNewEmail;
use ProtoneMedia\LaravelVerifyNewEmail\PendingUserEmail;

class User extends Authenticatable implements MustVerifyEmail
{
    use MustVerifyNewEmail, Notifiable;

    public function sendPendingEmailVerificationMail(PendingUserEmail $pendingUserEmail)
    {
        // send the mail...
    }
}

The package has a controller to handle the activation of the new email address. You can specify a custom route in the config file which will be used to generate the verification URL. The token will be passed in as a parameter and the URL will be signed.

<?php

return [

    'route' => 'user.email.verify',

];

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Other Laravel packages

  • Laravel Analytics Event Tracking: Laravel package to easily send events to Google Analytics.
  • Laravel Blade On Demand: Laravel package to compile Blade templates in memory.
  • Laravel Cross Eloquent Search: Laravel package to search through multiple Eloquent models.
  • Laravel Eloquent Scope as Select: Stop duplicating your Eloquent query scopes and constraints in PHP. This package lets you re-use your query scopes and constraints by adding them as a subquery.
  • Laravel Eloquent Where Not: This Laravel package allows you to flip/invert an Eloquent scope, or any query constraint.
  • Laravel FFMpeg: This package provides integration with FFmpeg for Laravel. The storage of the files is handled by Laravel's Filesystem.
  • Laravel Form Components: Blade components to rapidly build forms with Tailwind CSS Custom Forms and Bootstrap 4. Supports validation, model binding, default values, translations, includes default vendor styling and fully customizable!
  • Laravel Mixins: A collection of Laravel goodies.
  • Laravel Paddle: Paddle.com API integration for Laravel with support for webhooks/events.
  • Laravel WebDAV: WebDAV driver for Laravel's Filesystem.

Security

If you discover any security-related issues, please email pascal@protone.media instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.