Merge pull request #107 from leafsphp/staging

Staging

Author: mychidarko

src/docs/auth/protected-routes.md

@@ -102,6 +102,46 @@ app()->get('/login', ['middleware' => 'auth.guest', function () {
 
 If a logged in user tries to access a route protected by the `auth.guest` middleware, they will be redirected to the `/dashboard` route by default.
 
+## Email verification middleware <Badge>NEW</Badge>
+
+Leaf Auth provides middleware to protect routes that should only be accessible to only users with a certain email verification status. The `auth.verified` middleware ensures that only verified users can access certain routes.
+
+```php
+app()->group('/dashboard', [
+  'middleware' => 'auth.verified',
+  function () {
+    // dashboard routes will only be accessible to verified users
+  }
+]);
+
+app()->get('/some-route', [
+  'middleware' => 'auth.verified',
+  function () {
+    // route will only be accessible to verified users
+  }
+]);
+```
+
+While the `auth.unverified` middleware which ensures that only unverified users can access certain routes.
+
+```php
+app()->group('/verify', [
+  'middleware' => 'auth.unverified',
+  function () {
+    // verify routes will only be accessible to unverified users
+  }
+]);
+
+app()->get('/some-route', [
+  'middleware' => 'auth.verified',
+  function () {
+    // route will only be accessible to unverified users
+  }
+]);
+```
+
+By default, the `auth.verified` middleware will redirect unverified users to the `/auth/verify` route if they are not verified, and the `auth.unverified` middleware will redirect verified users to the `/dashboard` route if they are verified. You can customize this behaviour by defining your own function that should be called when the middleware fails. You can follow the instructions in the next section to learn how to customize the auth middleware.
+
 ## Customizing auth middleware
 
 Your application may need you to return different responses for the `auth.required` and `auth.guest` middleware. You can customize the middleware by defining your own function that should be called when the middleware fails.

src/docs/auth/user.md

@@ -31,6 +31,92 @@ $secretField = auth()->user()->secret_field;
 
 While this may seem like a lot of work, it's a good way to ensure that your user's data is secure and only accessible where needed.
 
+## Email verification <Badge>NEW</Badge>
+
+Email verification is a very important feature in most applications. It allows you to verify that the email address provided by a user is valid and that they have access to it. Leaf Auth by default does not incorporate email verification into the authentication process, but you can easily add it to your application using handy functions added in Auth v3.4.0.
+
+::: tip Database considerations
+Leaf does not enforce any database schema on you, however, Leaf will automatically create a nullable `email_verified_at` column in your users table if you do not have this column. No setup is required on your part.
+:::
+
+### Generating a verification token
+
+After you have registered a user, you can generate a verification token for the user using the `generateVerificationToken()` method. This method generates a JWT which you can send to the user's email address as part of a link.
+
+```php
+$token = auth()->user()->generateVerificationToken();
+
+$verificationLink = "https://example.com/verify?token=$token";
+```
+
+You can also pass an expiration time to the `generateVerificationToken()` method. The default expiration time is 10 minutes.
+
+```php:no-line-numbers
+$token = auth()->user()->generateVerificationToken(time() + 3600); // 1 hour
+```
+
+### Verifying a user
+
+When a user clicks on the verification link, you first need to verify the token. You can do this using the `verifyToken()` method. This method returns `true` if the token is valid and `false` if the token is invalid.
+
+```php
+$token = request()->get('token');
+$isValid = auth()->verifyToken($token);
+
+if ($isValid) {
+  // Token is valid
+} else {
+  // Token is invalid
+}
+```
+
+If the token is valid, you can then update the user's `email_verified_at` column to the current time. You can do this using the `verifyEmail()` method. This method returns `true` if the update is successful and `false` if the update is not successful.
+
+```php
+$token = request()->get('token');
+$isValid = auth()->verifyToken($token);
+
+if ($isValid && auth()->user()->verifyEmail()) {
+  // Email is verified
+} else {
+  // Could not verify email, missing or invalid token
+}
+```
+
+### Verification middleware
+
+You can also add a middleware to your routes and route groups to ensure that only users of a certain verification status can access certain routes.
+
+```php
+app()->get('/some-route', [
+  'middleware' => 'auth.verified',
+  function () {
+    // route will only be accessible to verified users
+  }
+]);
+
+app()->get('/some-route', [
+  'middleware' => 'auth.unverified',
+  function () {
+    // route will only be accessible to unverified users
+  }
+]);
+```
+
+You can view the full documentation on the [middleware page](/docs/auth/protected-routes.html#email-verification-middleware-new).
+
+### Checking verification status
+
+You can check if a user's email is verified using the `isVerified()` method. This method returns `true` if the user's email is verified and `false` if the user's email is not verified.
+
+```php
+if (auth()->user()->isVerified()) {
+  // Email is verified
+} else {
+  // Email is not verified
+}
+```
+
 ## User relationships
 
 Leaf auth comes with a very basic model system that allows you to get/set data related to the current user. For instance, you may want to get all posts by the current user or all transactions by the current user, or maybe add a new purchase to the current user. All these can be done using the user method.