The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-FormHandlerX-Form-Login
River stage zero No dependents
++
/ HTML::FormHandlerX::Form::Login

NAME

HTML::FormHandlerX::Form::Login - An HTML::FormHandler login form.

VERSION

Version 0.01

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 (kee...

 $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 email.

 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;
 }

Here we either use the email field, or the username. Process the form to ensure the params are valid.

You can then request the token, which you would send to the user to verify their email address.

Send them back to a URL with the token.

You need to specify a token_salt in order to get a token at all, otherwise the token will be an empty string.

Use add_token_field to include a field from the form in the token itself, you will want this to identify the user when they come to actually reset their password. You could put this in the URL yourself somehow, maybe with a user ID, but this is a little cleaner.

Every token will expire in 1 days time by default. you can override this with token_expires, either supplying an epoch timestamp, or a friendlier version, ie, 6m.

When the user follows your link containing the token, we will firstly validate that alone to ensure it has not been tampered with.

 $form = HTML::FormHandlerX::Form::Login->new( active => [ qw( token ) ] );
 
 $form->token_salt( 'SoMeThInG R4nD0M AnD PR1V4te' );
 
 $form->process( params => { token => $token } );
        
 if ( $form->validated ) { }

You need to specify the same salt as used previously.

Now render the form, the token is a hidden field, and the field added with add_reset_password_token_field will also be in the form.

Final validation comes when you have the new password along with 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 ) { }

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:

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.