DOCSP-38100: User authentication

Author: norareidy

docs/includes/auth/AuthController.php

@@ -0,0 +1,34 @@
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Validation\ValidationException;
+
+class AuthController extends Controller
+{
+   public function login(Request $request)
+   {
+      $request->validate([
+            'email' => 'required|email',
+            'password' => 'required',
+      ]);
+
+      if (Auth::attempt($request->only('email', 'password'))) {
+            return response()->json([
+               'user' => Auth::user(),
+               'message' => 'Successfully logged in',
+            ]);
+      }
+
+      throw ValidationException::withMessages([
+            'email' => ['The provided credentials are incorrect.'],
+      ]);
+   }
+
+   public function logout()
+   {
+      Auth::logout();
+
+      return response()->json(['message' => 'Successfully logged out']);
+   }
+}

docs/includes/auth/AuthUser.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Models;
+
+use Jenssegers\Mongodb\Auth\User as Authenticatable;
+
+class User extends Authenticatable
+{
+    protected $connection = 'mongodb';
+    protected $collection = 'users';
+
+    protected $fillable = [
+        'name',
+        'email',
+        'password',
+    ];
+
+    protected $hidden = [
+        'password',
+        'remember_token',
+    ];
+}

docs/user-authentication.txt

@@ -1,7 +1,7 @@
 .. _laravel-user-authentication:
 
 ===================
-User authentication
+User Authentication
 ===================
 
 .. facet::
@@ -11,14 +11,113 @@ User authentication
 .. meta::
    :keywords: php framework, odm, code example
 
-If you want to use Laravel's native Auth functionality, register this included
-service provider:
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+odm-long+} to create a ``User``
+model and configure user authentication.
+
+User Model
+----------
+
+By default, Laravel includes an ``App\Models\User`` Eloquent model in your ``app/Models``
+directory. You can extend the ``Jenssegers\Mongodb\Auth\User`` class to configure your
+``User`` model to use the Laravel Auth module, which provides multiple authentication services.
+To extend this class, navigate to your ``app/Models/User.php`` file and replace the
+``use Illuminate\Foundation\Auth\User as Authenticatable`` use statement with the following code:
+
+.. code-block:: php
+
+   use Jenssegers\Mongodb\Auth\User as Authenticatable;
+
+Ensure that your ``User`` class extends ``Authenticatable``, as shown in the following code:
+
+.. code-block:: php
+
+   class User extends Authenticatable
+   {
+   ...
+   }
+
+After configuring your ``User`` model, create a corresponding controller. For instructions on
+creating a controller, see the :ref:`laravel-auth-controller` section on this page.
+
+Example
+~~~~~~~
+
+The following code demonstrates a ``User.php`` file that extends the ``Jenssegers\Mongodb\Auth\User``
+class:
+
+.. literalinclude:: /includes/auth/AuthUser.php
+   :language: php
+   :dedent:
+
+.. _laravel-auth-controller:
+
+User Controller 
+---------------
+
+To store functions that manage authentication, create an authentication controller for
+your ``User`` model. 
+
+Run the following command from your project root to create a controller:
+
+.. code-block:: php
+
+   php artisan make:controller <filename>
+
+Example
+~~~~~~~
+
+The following command creates a controller file called ``AuthController.php``:
+
+.. code-block:: php
+
+   php artisan make:controller AuthController
+
+The ``AuthController.php`` file can store ``login()`` and ``logout()`` functions to
+manage user authentication, as shown in the following code: 
+
+.. literalinclude:: /includes/auth/AuthController.php
+   :language: php
+   :dedent:
+
+Enable Password Reminders 
+-------------------------
+
+To add support for MongoDB-based password reminders, register the following service
+provider in your application:
+
+.. code-block:: php
+
+   MongoDB\Laravel\Auth\PasswordResetServiceProvider::class
+
+This service provider modifies the internal ``DatabaseReminderRepository``
+to enable password reminders.
+
+Example
+~~~~~~~
+
+The following code updates the ``providers.php`` file in the ``bootstrap`` directory
+of a Laravel application to register the ``PasswordResetServiceProvider`` provider:
 
 .. code-block:: php
+   :emphasize-lines: 5
 
-   MongoDB\Laravel\Auth\PasswordResetServiceProvider::class,
+   return [
+     App\Providers\AppServiceProvider::class,
+     MongoDB\Laravel\MongoDBServiceProvider::class,
+     MongoDB\Laravel\Auth\PasswordResetServiceProvider::class
+   ];
 
-This service provider will slightly modify the internal ``DatabaseReminderRepository``
-to add support for MongoDB based password reminders.
+Additional Information
+----------------------
 
-If you don't use password reminders, you can omit this service provider.
+To learn more about user authentication, see `Authentication <https://laravel.com/docs/{+laravel-docs-version+}/authentication>`__
+in the Laravel documentation.