NAME
HTML::FormHandlerX::Form::Login - An HTML::FormHandler login form.
VERSION
Version 0.11
SYNOPSIS
Performs login form validation, including changing passwords, forgotten passwords, and resetting passwords.
If you are working under Catalyst, take a look at CatalystX::SimpleLogin.
Login with either an email
or username
parameter.
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password ) ] );
$form->process( params => { email => $email, password => $password } );
Changing a password...
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( old_password password confirm_password ) ] );
$form->process( params => { old_password => $old_password,
password => $password,
confirm_password => $confirm_password,
} );
Forgot password, just validates an email
, or username
.
Use this to create a token
to send to the user to verify their email address.
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email ) ] );
$form->process( params => { email => $email } );
if ( $form->validated )
{
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
my $token = $form->token;
}
Coming back from an email link, if the form validates, you would show the password reset form (carry the token in a hidden field or cookie).
$form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token ) ] );
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
$form->process( params => { token => $token } );
When trying to actually reset a password...
$form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token password confirm_password ) ] );
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
$form->process( params => { token => $token,
password => $password,
confirm_password => $confirm_password,
} );
DESCRIPTION
This module will validate your forms. It does not perform any actual authentication, that is still left for you.
Login
You can choose between email
and username
for the unique identifier.
Using email
brings in validation using Email::Valid.
email
/username
and password
are all required fields, so will fail validation if empty.
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email password ) ] );
$form->process( params => { email => $email, password => $password } );
Change Password
Instantiate the form by activating the 3 fields: old_password
, password
, and confirm_password
.
All 3 fields are required, and validation will also check the confirm_password
matches the password
.
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( old_password password confirm_password ) ] );
$form->process( params => { old_password => $old_password,
password => $password,
confirm_password => $confirm_password,
} );
if ( $form->validated ) { }
Forgot Password
Provide the email
or username
to validate, the form will then have a token
for you.
You can then send this token
to the user via email to verify their identity.
You need to supply a (private) token_salt
to make sure your token
s are not guessable. This can be anything you like.
Tokens expire by default after 24 hours from the date/time of issue. To change this, either supply an epoch timestamp of when to expire, or give a human-friendly format of how long to wait. We like things like:
2h - 2 hours
3d - 3 days
4w - 4 weeks
5m - 5 months
If you specify add_token_field
the value of this field in the form will be included in the token. This can be useful when the token is sent back, to identify the user.
my $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( email ) ] );
$form->process( params => { email => $email } );
if ( $form->validated )
{
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
$form->add_token_field( 'email' );
$form->token_expires( '3h' );
my $token = $form->token;
}
The token is comprised of a Digest::SHA hash, so can be a tad long, but has much less chance of collisions compared to an MD5.
Reset Password - Stage 1
You will usually give the token to the user in an email so they can verify they own the email address.
This step is for just showing the user a reset-password form.
The first step when the user comes back to reset their password, is to check they have not fiddled with the token.
You can safely skip this step, we check the token again when they/you actually try to change the password, this just lets you stop them in their tracks a little sooner.
Setting the token_salt
is required, and must obviously be the same salt
as used in the forgot-password call.
add_token_field
as you did during the forgot-password process. This ill populate the unique identifier field for you.
$form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token ) ] );
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
$form->add_token_field( 'email' );
$form->process( params => { token => $token } );
if ( $form->validated ) { }
Reset Password - Stage 2
You have now shown the user a form to enter a new password (and confirm it).
Either hidden in that form, or as a cookie, you have also stored the token.
$form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token password confirm_password ) ] );
$form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
$form->add_token_field( 'email' );
$form->process( params => { token => $token,
password => $password,
confirm_password => $confirm_password,
} );
if ( $form->validated ) { }
If you specified the token_field
as email
, you can now collect that from the form as the record to update safely.
$form->field( 'email' )->value;
And now know which user to update.
METHODS
Attributes
token
$form->token
Returns a unique string for the email
or username
validated by the form.
You typically send this to the users email.
token_fields
$form->add_token_field( 'email' );
Specifies which fields to include in the token for you to identify which user it is trying to reset their password when they come back.
Either email
or username
is normal.
token_salt
$form->token_salt
Your own (random string) salt used to create the reset-password token.
token_expires
$form->token_expires
Dictates how long the token is valid for, default is 1 day.
Possible formats are 2h, 3d, 6w, 1m, or an epoch timestamp.
Fields
token
$form->field('token')
This field is used when attempting to reset a password.
email / username
$form->field('email')
$form->field('username')
The username
field, or use the specific email
field for extra validation (employing Email::Valid).
old_password
$form->field('old_password')
Required when changing a known password.
password
$form->field('password')
Used for logging in, changing and/or resetting a password to something new.
confirm_password
$form->field('confirm_password')
Required for changing and/or resetting the password.
remember
$form->field('remember')
Useful for a "remember me" checkbox.
submit
$form->field('submit')
The submit button.
Validation
validate_email
The internal validation of the email address field, using Email::Valid.
validate_token
The internal validation of the token when attempting to reset a password.
html_attributes
This method has been populated to ensure all fields in error have the error
CSS class assigned to the labels.
AUTHOR
Rob Brown, <rob at intelcompute.com>
BUGS
Please report any bugs or feature requests to bug-html-formhandlerx-form-login at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-FormHandlerX-Form-Login. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc HTML::FormHandlerX::Form::Login
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormHandlerX-Form-Login
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
gshank: Gerda Shank <gshank@cpan.org>
t0m: Tomas Doran <bobtfish@bobtfish.net>
LICENSE AND COPYRIGHT
Copyright 2012 Rob Brown.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.