README

Confide is a authentication solution for Laravel4 using MongoLid made to eliminate repetitive tasks involving the management of users: Account creation, login, logout, confirmation by e-mail, password reset, etc.

Confide aims to be simple to use, quick to configure and flexible.

Note: If you are NOT using MongoDB check Confide.

Features

Current:

Account confirmation (through confirmation link).
Password reset (sending email with a change password link).
Easily render forms for login, signup and password reset.
Generate customizable routes for login, signup, password reset, confirmation, etc.
Generate a customizable controller that handles the basic user account actions.
Contains a set of methods to help basic user features.
Integrated with the Laravel Auth component/configs.
Field/model validation.
Login throttling.
Redirecting to previous route after authentication.

If you are looking for user roles and permissions see Entrust

Planned:

Captcha in user signup and password reset.
General improvements.

Quick start

Required setup

In the require key of composer.json file add the following

"zizaco/confide-mongo": "dev-master"

Run the Composer update comand

$ composer update

In your config/app.php add 'Zizaco\ConfideMongo\ConfideMongoServiceProvider' to the end of the $providers array

'providers' => array(

    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    'Illuminate\Auth\AuthServiceProvider',
    ...
    'Zizaco\ConfideMongo\ConfideMongoServiceProvider',

),

At the end of config/app.php add 'Confide' => 'Zizaco\Confide\ConfideFacade' to the $aliases array

'aliases' => array(

    'App'        => 'Illuminate\Support\Facades\App',
    'Artisan'    => 'Illuminate\Support\Facades\Artisan',
    ...
    'Confide'    => 'Zizaco\Confide\ConfideFacade',

),

Configuration

Set the driver to "mongoLid" in config/auth.php as stated in MongoLid Authentication:

    ...

    'driver' => 'mongoLid',
    
    ...

This values contained in config/auth.php will be used by Confide Mongo to generate the controllers and routes.

Set the address and name from the from array in config/mail.php. Those will be used to send account confirmation and password reset emails to the users.

User model

Change your User model in app/models/User.php to:

<?php

use Zizaco\ConfideMongo\ConfideMongoUser;

class User extends ConfideMongoUser {

}

ConfideMongoUser class will take care of some behaviors of the user model.

Dump the default acessors

Least, you can dump a default controller and the default routes for Confide.

$ php artisan confide:controller
$ php artisan confide:routes

Don't forget to dump composer autoload

$ composer dump-autoload

And you are ready to go. Access http://yourapp/user/create to create your first user. Check the app/routes.php to see the available routes.

Usage in detail

Basic setup:

Mongo database connection in config/database.php running properly.
Set the auth driver to "mongoLid" in config/auth.php.
Check and correct the model and collection names in config/auth.php. They will be used by Confide all the time.
from configuration in config/mail.php.

Configuration:

ConfideMongoServiceProvider and ConfideFacade entry in config/app.php 'providers' and 'aliases' respectively.
User model (with the same name as in config/auth.php) should extend ConfideMongoUser class. This will cause to methods like resetPassword(), confirm() and a overloaded save() to be available.

Optional steps:

Use Confide facade to dump login and signup forms easly with makeLoginForm() and makeSignupForm(). You can render the forms within your views by doing {{ Confide::makeLoginForm()->render() }}.
Generate a controller with the template contained in Confide throught the artisan command $ php artisan confide:controller. If a controller with the same name exists it will NOT be overwritten.
Generate routes matching the controller template throught the artisan command $ php artisan confide:routes. Your routes.php will NOT be overwritten.

Advanced

Using custom collection / model name

You can change the model name that will be authenticated in the config/auth.php file. Confide uses the values present in that configuration file.

To change the controller name when dumping the default controller template you can use the --name option.

$ php artisan confide:controller --name Employee

Will result in EmployeeController

Then, when dumping the routes, you should use the --controller option to match the existing controller.

$ php artisan confide:routes --controller Employee

Using custom form or emails

First, publish the config files:

$ php artisan config:publish zizaco/confide

Then edit the view names in app/config/packages/zizaco/confide/config.php.

Update an User

To update an user already in the database you'll want to either pass in an different rule set or use the amend function.

$user = new User;
$user->username = 'newUserName';

// Save
$user->save($this->getUpdateRules());

Validate model fields

To change the validation rules of the User model you can take a look at Laravel 4 Validations. For example:

<?php

use Zizaco\ConfideMongo\ConfideMongoUser;

class User extends ConfideMongoUser {

    /**
     * Validation rules
     */
    public static $rules = array(
        'email' => 'required|email',
        'password' => 'required|between:4,11|confirmed',
    );

}

Feel free to add more fields to your collection and to the validation array. Then you should build your own sign-up form with the additional fields.

Passing additional information to the make methods

If you want to pass additional parameters to the forms, you can use an alternate syntax to achieve this.

Instead of using the make method:

Confide::makeResetPasswordForm( $token ):

You would use:

View::make(Config::get('confide::reset_password_form'))
    ->with('token', $token);

It produces the same output, but you would be able to add more inputs using 'with' just like any other view.

RESTful controller

If you want to generate a RESTful controller you can use the aditional --restful or -r option.

$ php artisan confide:controller --restful

Will result in a RESTful controller

Then, when dumping the routes, you should use the --restful option to match the existing controller.

$ php artisan confide:routes --restful

User roles and permissions

In order not to bloat Confide with not related features, the role and permission was developed as another package: Entrust. This package couples very well with Confide.

See Entrust

Note: Entrust is not yet available for MongoLid / MongoDB

Redirecting to previous route after login

When defining your filter you should set the 'loginRedirect' session variable. For example:

// filters.php

Route::filter('auth', function()
{
    if ( Auth::guest() ) // If the user is not logged in
    {
        // Set the loginRedirect session variable
        Session::put( 'loginRedirect', Request::url() );

        // Redirect back to user login
        return Redirect::to( 'user/login' );
    }
});

// Only authenticated users will be able to access routes that begins with
// 'admin'. Ex: 'admin/posts', 'admin/categories'.
Route::when('admin*', 'auth');

or, if you are using Entrust ;)

// filters.php

Entrust::routeNeedsRole( 'admin*', 'Admin', function(){
    Session::put( 'loginRedirect', Request::url() );
    return Redirect::to( 'user/login' );
} );

Validating a route

If you want to validate whether a route exists, the Confide::checkAction function is what you are looking for.

Currently it is used within the views to determine Non-RESTful vs RESTful routes.

Troubleshooting

"'confirmation_code' required" when creating a user

If you overwrite the save() method in your model, make sure to call parent::save():

public function save( $forced = false ){

    parent::save( $forced) // Don't forget this

    // Your stuff
}

Confirmation link is not sent when user signup

If you overwrite the afterSave() method in your model, make sure to call parent::afterSave()

Users are able to login without confirming account

If you want only confirmed users to login, in your UserController, instead of simply calling logAttempt( $input ), call logAttempt( $input, true ). The second parameter stands for "confirmed_only".

License

Confide is free software distributed under the terms of the MIT license

Aditional information

Any questions, feel free to contact me or ask here

Any issues, please report here

zizaco / confide-mongo

Maintainers

Details