search

Zizaco / confide

Confide is a authentication solution for Laravel 4
1.19k stars 258 forks source link

readme

Confide (A Laravel4 Package)

Confide Poster

Build Status Coverage Status Scrutinizer Code Quality ProjectStatus Latest Stable Version Total Downloads License

SensioLabsInsight

Confide is an authentication solution for Laravel made to cut repetitive work involving the management of users. A DRY approach on features like 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 using MongoDB check Confide Mongo.

Features

Current:

If you are looking for user roles and permissions see Entrust

For MongoDB support see Confide Mongo

Warning: _By default a confirmation email is sent and users are required to confirm the email address. It is easy to change this in the confide config file. Change signup_email and signup_confirm to false if you do not want to send them an email and they do not need to be confirmed to be able to login to the website._

Quick start

Required setup

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

"zizaco/confide": "~4.3@dev"

Run the Composer update comand

$ composer update

In your config/app.php add 'Zizaco\Confide\ServiceProvider' to the end of the providers array

'providers' => array(

    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    'Illuminate\Auth\AuthServiceProvider',
    ...
    'Zizaco\Confide\ServiceProvider',

),

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

'aliases' => array(

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

),

Configuration

Set the properly values to the config/auth.php. This values will be used by confide to generate the database migration and to generate 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

Now generate the Confide migration and the reminder password table migration:

$ php artisan confide:migration

It will generate the <timestamp>_confide_setup_users_table.php migration. You may now run it with the artisan migrate command:

$ php artisan migrate

It will setup a table containing email, password, remember_token, confirmation_code and confirmed columns, which are the default fields needed for Confide use. Feel free to add more columns to the table later.

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

<?php

use Zizaco\Confide\ConfideUser;
use Zizaco\Confide\ConfideUserInterface;

class User extends Eloquent implements ConfideUserInterface
{
    use ConfideUser;
}

ConfideUser trait will take care of some behaviors of the user model.

Dump the default accessors

Lastly, you can dump a default controller, repository 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/users/create to create your first user. Check the app/routes.php to see the available routes. You may need to confirm a newly created user (by "reaching" its confirm() method), otherwise you can disable the confirmation as a requirement to login in in the config file (see bellow).

Usage in detail

Basic setup:

  1. Database connection in config/database.php running properly.
  2. Correct model and table names in config/auth.php. They will be used by Confide all the time (specially when generating migrations and controllers).
  3. from configuration in config/mail.php.

Configuration:

  1. 'Zizaco\Confide\ServiceProvider' and 'Confide' => 'Zizaco\Confide\Facade' entry in config/app.php 'providers' and 'aliases' respectively.
  2. User model (with the same name as in config/auth.php) should implement Zizaco\Confide\ConfideUserInterface interface. This will cause to methods like forgotPassword() and confirm() to be available.

Optional steps:

  1. Optionally you can use the trait Zizaco\Confide\ConfideUser in your user model. This will save a lot of time and will use "confide's default" implementation for the user. If you wish more customization you can write your own code.
  2. 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() }}.
  3. Generate a controller and a repository 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.
  4. Generate routes matching the controller template throught the artisan command $ php artisan confide:routes. Don't worry, your routes.php will NOT be overwritten.

Advanced

The UserRepository class

You may have noticed that when generating the controller a UserRepository class has also been created. This class contains some code that doesn't belong to the "controller" purpose and will make your users controller a cleaner and more testable class. If you still have no idea why that class exists I recommend you to google "Creating flexible Controllers in Laravel 4 using Repositories". (wink)

Using custom class, table or model name

You can change the model name that will be considered the user 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

You can also generate controllers with namespace

$ php artisan confide:controller --name=MyProject\\Auth\\User

Warning: In bash, you will need to use double '\\' backslashes. This will result in MyProject\Auth\UserController. Also the generated file will be inside a directory equivalent to the namespace. (wink)

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.

Seeding

To seed your users table you should fill also the password_confirmation and confirmation_code fields. For example:

class UsersTableSeeder extends Seeder {

    public function run()
    {
        $user = new User;
        $user->email = 'johndoe@site.dev';
        $user->password = 'foo_bar_1234';
        $user->password_confirmation = 'foo_bar_1234';
        $user->confirmation_code = md5(uniqid(mt_rand(), true));
        $user->confirmed = 1;

        if(! $user->save()) {
            Log::info('Unable to create user '.$user->email, (array)$user->errors());
        } else {
            Log::info('Created user '.$user->email);
        }
    }
}

Custom user validation

You can implement your own validator by creating a class that implements the UserValidatorInterface and registering that class as "confide.user_validator".

For example, create your custom validator class:

// app/models/MyOwnValidator.php
class MyOwnValidator implements UserValidatorInterface
{

    public function validate(ConfideUserInterface $user)
    {
        unset($user->password_confirmation);
        return true; // If the user valid
    }
}

Then register it in IoC container as "confide.user_validator"

// app/start/global.php
//...
App::bind('confide.user_validator', 'MyOwnValidator');

Also, don't forget that your validator should unset the 'password_confirmation' attribute of the user before saving it.

Passing additional information to the "make" methods

If you want to pass additional parameters to the forms being rendered, 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. Enstrust couples very well with Confide.

See Entrust

Redirecting to previous route after login

When defining your filter you should use the Redirect::guest('users/login') within your auth filter. For example:

// filters.php

Route::filter('auth', function () {
    // If the user is not logged in
    if (Auth::guest()) {
        return Redirect::guest('users/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 () {
    return Redirect::guest('users/login');
});

Finally, it'll auto redirect if your controller's users/login function uses Redirect:intended('a/default/url/here') after a successful login. The generated controller does exactly this.

Troubleshooting

__[2014-07-18 01:13:15] production.ERROR: exception 'Illuminate\Database\QueryException' with message 'SQLSTATE[42S22]: Column not found: 1054 Unknown column 'password_confirmation' in 'field list' (SQL: insert into `users` ...__

The password_confirmation attribute should be removed from the object before being sent to the database. Make sure your user model implement the ConfideUserInterface and that it use the ConfideUser trait as described above. Otherwise if you are using a custom validator, you will have to unset password_confirmation before saving the user.

I need my users to have an "username"

Use the --username option when generating the confide migration and the controller.

$ php artisan confide:migration --username
...
$ php artisan confide:controller --username

If you want to make the username a required field you will have to extend the UserValidator and overwrite the $rules attribute making the "username" required.

I receive a "Your account may not be confirmed" when trying to login

You need to confirm a newly created user (by "reaching" its confirm() method), otherwise you can disable the confirmation as a requirement to login in in the config file (see bellow). You can easly confirm an user manually using Laravel's artisan tinker tool.

I'm not able to generate a controller with namespaces

In bash, you will need to use double '\\' backslashes. Also the generated file will be inside a directory equivalent to the namespace:

$ php artisan confide:controller --name=MyProject\\Auth\\User

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 _"confirmedonly".

My application is crashing since I ran composer update

Confide 4.0.0 was a huge update where all the codebase has been rewritten. Some classes changed, the generators has been improved in order to match some better practices (like repositories and separated validator classes). See the Release Notes bellow.

If you have a legacy project that uses an older version of Confide, don't worry. You will be always able to specify a previous version in your composer.json file.

For example: "zizaco/confide": "~3.2" will avoid composer download version 4.0 but will be able to download bugfixes of version 3.2.

Release Notes

Version 4.3.0 Beta 1

Version 4.2.0

Version 4.0.0 RC

Version 4.0.0 Beta 3

Version 4.0.0 Beta 2

Version 4.0.0 Beta 1

Upgrade note: A partial update from previous versions is not recommended. In order to upgrade from v3.* to v4.0.0 the best approach is to update the class names in the providers and aliases array, re-generate the user table with the new migration, re-write the "user" class and finally re-generate the controllers. It's very likely any customization made in your codebase will be affected.

Version 3.0.0

Updated to support Laravel 4.1

Version 2.0.0 Beta 4

Removed deprecated variable and functions.

Adds two config values

Version 2.0.0 Beta 3

Readme Update

Version 2.0.0 Beta 2

Pulls in a few pull requests and also locks to Ardent 2.1.x

Version 2.0.0 Beta 2

Locked to Ardent 1.1.x

Version 1.1.0

Contributing

Feel free to fork this project on GitHub

Coding Standards

When contibuting code to confide, you must follow its coding standards. Confide follows the standard defined in the PSR-2 document.

Documentation

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