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.phprunning 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). fromconfiguration 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\ConfideUserInterfaceinterface. This will cause to methods likeforgotPassword()andconfirm()to be available.
Optional steps:
- Optionally you can use the trait
Zizaco\Confide\ConfideUserin 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
Confidefacade 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.phpwill 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 = '[email protected]';
$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
--usernamewhen 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.
validateIsUniquemethod now sends key to attachErrorMsg and also check for errors on each$identityfield 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
@returntag if the method does not return anything - Add a blank line before
@param,@returnand@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
10 Aug 3, 2022
34 Feb 14, 2022
780 Dec 24, 2022
1.4k Jan 6, 2023
1.2k Dec 22, 2022
10 Dec 14, 2021
2.8k Dec 31, 2022
10.7k Dec 31, 2022
894 Dec 28, 2022
69 Jul 14, 2022
2.1k Jan 3, 2023
17 Jul 17, 2022
33 Aug 19, 2019
26 Jun 20, 2021
2 Oct 19, 2021
490 Dec 27, 2022