Confide (A Laravel4 Package)
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:
- Account confirmation (through confirmation link).
- Password reset (sending email with a change password link).
- Easily render forms for login, signup and password reset.
- Generate 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 with basic user features.
- Integrated with the Laravel Auth and Reminders component/configs.
- User validation.
- Login throttling.
- Redirecting to previous route after authentication.
- Checks for unique email and username in signup
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:
- Database connection in
config/database.php
running properly. - Correct model and table names in
config/auth.php
. They will be used by Confide all the time (specially when generating migrations and controllers). from
configuration inconfig/mail.php
.
Configuration:
'Zizaco\Confide\ServiceProvider'
and'Confide' => 'Zizaco\Confide\Facade'
entry inconfig/app.php
'providers'
and'aliases'
respectively.- User model (with the same name as in
config/auth.php
) should implementZizaco\Confide\ConfideUserInterface
interface. This will cause to methods likeforgotPassword()
andconfirm()
to be available.
Optional steps:
- 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. - Use
Confide
facade to dump login and signup forms easly withmakeLoginForm()
andmakeSignupForm()
. You can render the forms within your views by doing{{ Confide::makeLoginForm()->render() }}
. - 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. - Generate routes matching the controller template throught the artisan command
$ php artisan confide:routes
. Don't worry, yourroutes.php
will NOT be overwritten.
Advanced
UserRepository
class
The 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 "confirmed_only".
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
- Username is now an optional field. Use
--username
when generating the migrations and the controllers. - General Bugfixes.
Version 4.2.0
- General Bugfixes.
- Improved README.md.
- Improved existing translations and added new ones.
Version 4.0.0 RC
- General Bugfixes.
- Improved README.md.
- Confide can use queues for sending email.
- Account confirmation tokens are not time-based anymore.
Version 4.0.0 Beta 3
- Now you can customize how long will take for a password reset request to expire (default to 7 hours).
- Reordered validations
- Now all validations are called even if one of them fails. So all validation messages are sent at once.
validateIsUnique
method now sends key to attachErrorMsg and also check for errors on each$identity
field at once
Version 4.0.0 Beta 2
- UserValidator now adds errors to an existing MessageBag instead of replacing it.
- Password reset token will expire after 7 days.
- Added support for custom connections using the $connection attribute of the model.
- Password reset requests are deleted after being used.
Version 4.0.0 Beta 1
- Dropped Ardent dependency.
- Updated to support Laravel 4.2
- Dropped support for PHP 5.3
- ConfideUser is going to be a trait+interface from now on.
- Controller generation now also generates an UserRepository class.
- Removed deprecated variables, functions and classes.
- All the codebase has been rewritten.
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.
- $updateRules
- amend()
- generateUuid
- getUpdateRules
- prepareRules
- getRules
- setUpdateRules
- getUserFromCredsIdentity
- checkUserExists
- isConfirmed
Adds two config values
- login_cache_field (#161)
- throttle_time_period (#162)
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
- Properly handles validation messaging (#124)
- Properly validates in real_save (#110)
- Auth redirect is handled using Redirect::guest instead of a custom session variable (#145)
- Bruteforce vulnerability is addressed. (#151)
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
- Add PHPDoc blocks for all classes, methods, and functions
- Omit the
@return
tag if the method does not return anything - Add a blank line before
@param
,@return
and@throws
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