Club, Laravel authentication made simple
Club is an authentication module made to work with Laravel 4 with minimal configuration and no other dependencies., (*1)
Installation in 4 easy steps
1. Add club to your composer.json.
{
"require": {
"laravel/framework": "4.2.*",
...
"lud/club": "~1.0"
}
}
2. Update dependencies
Update your dependencies with composer from the shell., (*2)
composer update
3. Add the service provider
Just add 'Lud\Club\ClubServiceProvider',
to the end of the providers array in app/config/app.php
:, (*3)
// ...
'providers' => array(
'Illuminate\Foundation\Providers\ArtisanServiceProvider',
'Illuminate\Auth\AuthServiceProvider',
// * snip *
'Lud\Club\NovelServiceProvider',
),
// ...
4. Create tables & migrate
Run the following commands in the shell :, (*4)
4.1 Create the users table
php artisan club:users-table
This will generate a migration in app/database/migrations called ..._create_club_users_table.php
. This migration creates the table to store your users. You can change the content of this file to suit your needs., (*5)
4.2 Create the users table
php artisan auth:reminders-table
This will create a migration called ..._create_password_reminders_table.php
. Again, you can change the file if you need so. This migration creates a table to store password reminders tokens ("Lost Password" functionality)., (*6)
4.3 Create the users table
php artisan migrate
This will execute the migrations., (*7)
4.4 (Optional) Model & table configuration
Note that the table name depends on the auth.model
configuration value. The default value is 'User'
, so the migration will create a users
table., (*8)
Check your app/config/auth.php
file if you need to change that., (*9)
You can also change the table name by modifying your model :, (*10)
class User extends Eloquent {
protected $table = 'another_table';
}
Test
Now, go to http://localhost:8000/signup (change the URL accordingly to your Laravel setup / web server), you can register to your site., (*11)
There are many chances like you see things like validation.attributes.email
. This will change, now that Laravel handles package's lang files properly. But at the moment you will need to add these strings to your app/lang/xx/validation.php
file (where xx
is a lang code as en
or fr
)., (*12)
Club Configuration
Club works well with the default configuration, but you may want to tune a bit your installation. To do so, first publish the configuration to you app space, so you can properly update the Club package., (*13)
php artisan config:publish lud/club
You can now check the config file at app/config/packages/lud/club/config.php
. Here is a simple explanation of each key/value but you may want to post an issue in the Club's Github repository., (*14)
1. Controller
This option let you specify which controller Club's routes are mapped to. You may wan copy the ClubController
and add changes to your copy., (*15)
2. Routes prefix
This option allow you to change Club's URLs with a prefix, useful when you have other routes that conflict with Club. If you set 'prefix' => 'myprefix',
, the login page URL will be /myprefix/login
., (*16)
All club routes have a route name. You can write a URL to any of these by using URL::route('<route-name>')
; the prefix is automatically added., (*17)
The routes names and URLs (without prefix) are described here :, (*18)
Route Name |
URL |
club.signup |
/signup |
club.login |
/login |
club.lost_password |
/lost-password |
club.reset_password_access |
/reset-password/{token} |
club.logout |
/logout . |
Use routes on filters
If you set a route prefix, you need to change your auth filter in app/filters.php
. Use the Club route name to the login page., (*19)
// ...
else
{
return Redirect::guest('login');
... will become ..., (*20)
// ...
else
{
return Redirect::route('club.login');
3. Default login/logout redirect
This are the URLs where a redirection is made to on login/logout if we cannot do a better redirection (see next)., (*21)
4. Login/out "No redirect" ("Stay on the page")
This option allows the user to stay on the same page when clicking "login" or "logout" links. You don't want your site to send all of your users to the homepage when they log in or sign up., (*22)
- The
'all'
option adds this functionality to any named route.
- The
null
option disables this functionality entirely.
- An array of routes names enables this functionality for these routes only, e.g.
array('my_route','my_resource.show')
5. Views
You may want to change the Club views to add customization. Just execute this command :, (*23)
php artisan view:publish lud/club
All the views will be present in app/views/packages/lud/club
., (*24)
5.1 Architecture
All Club forms are stored in their own blade template, in the include
subdirectory of the Club views. For each form we have a wrapper, stored in the views directory, extending the default layout base.blade.php
present in the layouts
subdirectory., (*25)
Back to the configuration file, for each Club page, we have a value in the views
array e.g. 'signup' => 'club::signup_form_wrapper'
. This means that to render the signup
page, we call the club::signup_form_wrapper
view., (*26)
We also have a base_layout
configuration value, set to club::layouts.base
. This makes club::signup_form_wrapper
extend this view., (*27)
5.2 The easy way
So, the most easy thing to do is to change the 'base_layout'
config to set your own layout. You just need to define a 'club'
section in it :, (*28)
@section('club')
@show
5.3 The hard way
If you need more control, just fill up the 'views'
array with your own view names in the configuration. The club controller will now call these views. In your blade files, you can still include the forms :, (*29)
@include('club::include.signup_form')
6. Emails
To setup "lost password" functionality, you must use the club.reset_password_access
route in your reminder email., (*30)
Check the config.auth.reminder.email
configuration value in your app/config/auth.php
file. This is the name of the view rendering the email that it sent to your users. You should replace {{ URL::to('password/reset', array($token)) }}
with {{ URL::route('club.reset_password_access', array($token)) }}
in this view., (*31)
You can also set the configuration to 'club::emails.reminder_email'
. This is the default Laravel view with the right route., (*32)
User Validation
You can add validation rules to your model class for automatic validation whenever a User
(or whatever model you chose to use) is updated., (*33)
The default validation rules are the following :, (*34)
class User extends Eloquent {
// ...
public $rules = array(
'email' => 'required|email|unique:'.$this->getTable().',email',
'password' => 'required|min:3'
);
// ...
}
Feel free to set your own rules according to the Laravel documentation., (*35)
Roadmap
- Enable "Stay on the page" when clicking signup
- Document UserRolesTrait
- Allow to login without email : provide way to choose arbitrary fields (e.g.
username
).
-
stay_on_page
default should be null
?
- Finish the docs
- Use L5 features (Request/AuthController/LoginRequest ?)
- Document L5 Installation