More documentation work

Author: stevebauman

docs/auth/fallback.md

@@ -1,6 +1,8 @@
 # Installation
 
-### Laravel 5.1
+The installation process slightly differs depending on your  Laravel version. Please look at the install guide with the Laravel version you're using.
+
+## Laravel 5.0 - 5.1
 
 Insert the `AdldapAuthServiceProvider` into your `config/app.php` file:
 
@@ -11,16 +13,16 @@ Adldap\Laravel\AdldapAuthServiceProvider::class,
 Publish the auth configuration:
 
 ```bash
-php artisan vendor:publish --tag="adldap"
+php artisan vendor:publish --provider="Adldap\Laravel\AdldapAuthServiceProvider"
 ```
 
-Change the auth driver in `config/auth.php` to `adldap`:
+Change the auth driver in `config/auth.php` to `ldap`:
 
 ```php
-'driver' => 'adldap',
+'driver' => 'ldap',
 ```
 
-### Laravel 5.2 - 5.4
+## Laravel 5.2 - 5.4
 
 Insert the `AdldapAuthServiceProvider` into your `config/app.php` file:
 
@@ -31,40 +33,42 @@ Adldap\Laravel\AdldapAuthServiceProvider::class,
 Publish the auth configuration file:
 
 ```bash
-php artisan vendor:publish --tag="adldap"
+php artisan vendor:publish --provider="Adldap\Laravel\AdldapAuthServiceProvider"
 ```
 
 Open your `config/auth.php` configuration file and change the following:
 
-Change the `driver` value inside the `users` authentication provider to `adldap`:
+Change the `driver` value inside the `users` authentication provider to `ldap`:
 
 ```php
 'providers' => [
     'users' => [
-        'driver' => 'adldap', // Changed from 'eloquent'
+        'driver' => 'ldap', // Changed from 'eloquent'
         'model' => App\User::class,
     ],
 ],
 ```
 
-### Laravel 5.5
+## Laravel 5.5
 
 When using Laravel 5.5, the service providers are registered automatically,
-however you will still need to publish the configuration files using the
+however you will still need to publish the configuration file using the
 command below:
 
 ```bash
-php artisan vendor:publish --tag="adldap"
+php artisan vendor:publish --provdier="Adldap\Laravel\AdldapAuthServiceProvider"
 ```
 
 Then, open your `config/auth.php` configuration file and change the `driver`
-value inside the `users` authentication provider to `adldap`:
+value inside the `users` authentication provider to `ldap`:
 
 ```php
 'providers' => [
     'users' => [
-        'driver' => 'adldap', // Changed from 'eloquent'
+        'driver' => 'ldap', // Changed from 'eloquent'
         'model' => App\User::class,
     ],
 ],
-```
+```
+
+Now that you've completed the basic installation, let's move along to the [setup guide](setup.md).

docs/auth/installation.md

@@ -1,7 +1,157 @@
 # Introduction
 
-The Adldap2 Laravel auth driver allows you to seamlessly authenticate LDAP users,
-as well as have a local database record of the user.
+The Adldap2 Laravel auth driver allows you to seamlessly authenticate LDAP users into your Laravel application.
 
-This allows you to easily attach information to the users account
-as you would a regular laravel application.
+There are two primary ways of authenticating LDAP users:
+
+- Authenticate and synchronize LDAP users into your local applications database:
+
+    This allows you to attach data to users as you would in a traditional application.
+
+    Calling `Auth::user()` returns your configured Eloquent model (ex. `App\User`) of the LDAP user.
+
+- Authenticate without keeping a database record for users
+
+    This allows you to have temporary users.
+
+    Calling `Auth::user()` returns the actual LDAP users model (ex. `Adldap\Models\User`).
+
+We'll get into each of these methods and how to implement them, but first, lets go through the [installation guide](installation.md).
+
+## Quick Start - From Scratch
+
+Here is a step by step guide for configuring Adldap2-Laravel (and its auth driver) with a fresh new laravel project. This guide assumes you have knowledge working with:
+
+- Laravel
+- The LDAP Protocol
+- Your LDAP distro (ActiveDirectory, OpenLDAP, FreeIPA)
+- Command line tools (such as Composer and Laravel's Artisan).
+
+This guide was created with the help of [@st-claude](https://github.com/st-claude) and other awesome contributors.
+
+1. Create a new laravel project by running the command:
+  - `laravel new my-ldap-app`
+  
+  Or (if you don't have the [Laravel Installer](https://laravel.com/docs/5.7#installation))
+ 
+  - `composer create-project --prefer-dist laravel/laravel my-app`.
+
+2. Run the following command to install Adldap2-Laravel:
+
+  - `composer require adldap2/adldap2-laravel`
+
+3. Create a new database in your desired database interface (such as PhpMyAdmin, MySQL Workbench, command line etc.)
+
+4. Enter your database details and credentials inside the `.env` file located in your project root directory (if there is not one there, rename the `.env.example` to `.env`).
+
+5. If you're using username's to login users **instead** of their emails, you will need to change
+   the default `email` column in `database/migrations/2014_10_12_000000_create_users_table.php`.
+   
+    ```php
+    // database/migrations/2014_10_12_000000_create_users_table.php
+       
+    Schema::create('users', function (Blueprint $table) {
+        $table->increments('id');
+        $table->string('name');
+          
+        // From:
+        $table->string('email')->unique();
+          
+        // To:
+        $table->string('username')->unique();
+          
+        $table->string('password');
+        $table->rememberToken();
+        $table->timestamps();
+    });
+    ```
+   
+6. Now run `php artisan migrate`.
+
+7. Insert the following service providers in your `config/app.php` file (in the `providers` array):
+
+    > **Note**: This step is only required for Laravel 5.0 - 5.4.
+    > They are registered automatically in Laravel 5.5.
+
+   ```php
+   Adldap\Laravel\AdldapServiceProvider::class,
+   Adldap\Laravel\AdldapAuthServiceProvider::class,
+   ```
+
+8. Now, insert the facade into your `config/app.php` file (in the `aliases` array):
+
+   ```php
+   'Adldap' => Adldap\Laravel\Facades\Adldap::class,
+   ```
+
+   > **Note**: Insertion of this alias in your `app.php` file isn't necessary unless you're planning on utilizing it.
+
+9. Now run `php artisan vendor:publish` in your root project directory to publish Adldap2's configuration files.
+
+    *  Two files will be published inside your `config` folder, `ldap.php` and `ldap_auth.php`.
+
+10. Modify the `config/ldap.php` and `config/ldap_auth.php` files for your LDAP server configuration.
+
+11. Run the command `php artisan make:auth` to scaffold login controllers and routes.
+
+12. If you require logging in by another attribute, such as a username instead of email follow
+the process below for your Laravel version. Otherwise ignore this step.
+
+ **Laravel <= 5.2**
+
+  Inside the generated `app/Http/Controllers/Auth/AuthController.php`, you'll need to add the `protected $username` property if you're logging in users by username.
+
+  ```php
+  class AuthController extends Controller
+  {
+      protected $username = 'username';
+  ```
+
+ **Laravel > 5.3**
+
+  Inside the generated `app/Http/Controllers/Auth/LoginController.php`, you'll need to add the public method `username()`:
+
+  ```php
+  public function username()
+  {
+      return 'username';
+  }
+  ```
+
+13. Now insert a new auth driver inside your `config/auth.php` file:
+
+  ```php
+  'providers' => [
+      'users' => [
+          'driver' => 'ldap', // Was 'eloquent'.
+          'model'  => App\User::class,
+      ],
+  ],
+  ```
+
+14. Inside your `resources/views/auth/login.blade.php` file, if you're requiring the user logging in by username, you'll
+    need to modify the HTML input to `username` instead of `email`. Ignore this step otherwise.
+
+    From:
+    ```html
+    <input type="email" class="form-control" name="email" value="{{ old('email') }}">
+    ```
+
+    To:
+
+    ```html
+    <input type="text" class="form-control" name="username" value="{{ old('username') }}">
+    ```
+
+15. You should now be able to login to your Laravel application using LDAP authentication!
+
+    If you check out your database
+  in your `users` table, you'll see that your LDAP account was synchronized to a local user account.
+  
+  
+    This means that
+  you can attach data regularly to this user as you would with standard Laravel authentication.
+
+    If you're having issues, and you're unable to authenticate LDAP users, please check your configuration settings inside the `ldap.php` and `ldap_auth.php` files as these directly impact your applications ability to  authenticate.
+
+16. Congratulations, you're awesome.