view release on metacpan or  search on metacpan

lib/App/ZofCMS/Plugin/UserLogin/ForgotPassword.pm  view on Meta::CPAN

    plug_user_login_forgot_password => {
        # mandatory
        dsn                  => "DBI:mysql:database=test;host=localhost",

        # everything below is optional...
        # ...arguments' default values are shown
        user                 => '',
        pass                 => undef,
        opt                  => { RaiseError => 1, AutoCommit => 1 },
        users_table          => 'users',
        code_table           => 'users_forgot_password',
        q_code               => 'pulfp_code',
        max_abuse            => '5:10:60', # 5 min. intervals, max 10 attempts per 60 min.
        min_pass             => 6,
        code_expiry          => 24*60*60, # 1 day
        code_length          => 6,
        subject              => 'Password Reset',
        email_link           => undef, # this will be guessed
        from                 => undef,
        email_template       => undef, # use plugin's default template
        create_table         => undef,
        login_page           => '/',
        mime_lite_params     => undef,
        email                => undef, # use `email` column in users table
        button_send_link => q|<input type="submit" class="input_submit"|
            . q| value="Send password">|,
        button_change_pass => q|<input type="submit" class="input_submit"|
            . q| value="Change password">|,
        use_stage_indicators => 1,
        no_run               => undef,
    },

=head1 DESCRIPTION

The module is a plugin for L<App::ZofCMS> that adds functionality to
L<App::ZofCMS::Plugin::UserLogin> plugin; that being the "forgot password?"
operations. Namely, this involves showing the user the form to ask for
their login, emailing the user special link which to follow (this is to
establish ligitimate reset) and, finally, to provide a form where a user
can enter their new password (and of course, the plugin will update
the password in the C<users> table). Wow, a mouthful of functionality! :)

This documentation assumes you've read L<App::ZofCMS>, L<App::ZofCMS::Config> and L<App::ZofCMS::Template>. Whilst not necessary,
being familiar with L<App::ZofCMS::Plugin::UserLogin> might be helpful.

=head1 GENERAL OUTLINE OF THE WAY PLUGIN WORKS

Here's the big picture of what the plugin does: user visits a page, plugin
shows the HTML form that asks the user to enter their login in order to
request password reset.

Once the user does that, the plugin checks that the provided login indeed
exists, checks that there's no abuse going on (flooding with reset
requests), generates a special "code" that, as part of a full
link-to-follow, is sent to the user inviting them to click it to proceed
with the reset.

Once the user clicks the link in their email (and thus ends up back on your
site), the plugin will invite them to enter (and reenter to confirm)
their new password. Once the plugin ensures the password looks good,
it will update user's password in the database.

All this can be enabled on your site with a few keystroke, thanks to this
plugin :)

=head1 FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

=head2 C<plugins>

    plugins => [
        { 'UserLogin::ForgotPassword' => 2000 },
    ],

B<Mandatory>. You need to include the plugin in the list of plugins
to execute.

=head2 C<plug_user_login_forgot_password>

    plug_user_login_forgot_password => {
        # mandatory
        dsn                  => "DBI:mysql:database=test;host=localhost",

        # everything below is optional...
        # ...arguments' default values are shown
        user                 => '',
        pass                 => undef,
        opt                  => { RaiseError => 1, AutoCommit => 1 },
        users_table          => 'users',
        code_table           => 'users_forgot_password',
        q_code               => 'pulfp_code',
        max_abuse            => '5:10:60', # 5 min. intervals, max 10 attempts per 60 min.
        min_pass             => 6,
        code_expiry          => 24*60*60, # 1 day
        code_length          => 6,
        subject              => 'Password Reset',
        email_link           => undef, # this will be guessed
        from                 => undef,
        email_template       => undef, # use plugin's default template
        create_table         => undef,
        login_page           => '/',
        mime_lite_params     => undef,
        email                => undef, # use `email` column in users table
        button_send_link => q|<input type="submit" class="input_submit"|
            . q| value="Send password">|,
        button_change_pass => q|<input type="submit" class="input_submit"|
            . q| value="Change password">|,
        use_stage_indicators => 1,
        no_run               => undef,
    },

    # or
    plug_user_login_forgot_password => sub {
        my ( $t, $q, $config ) = @_;
        ...
        return $hashref_to_assign_to_plug_user_login_forgot_password_key;
    },

B<Mandatory>. Takes either a hashref or a subref as a value.
If subref is specified, its return value will be assigned to
C<plug_user_login_forgot_password> key as if it was already there.

lib/App/ZofCMS/Plugin/UserLogin/ForgotPassword.pm  view on Meta::CPAN

C<users_table> table.

=head2 C<plug_forgot_password_stage_ask_error_abuse>

    <tmpl_if name='plug_forgot_password_stage_ask_error_abuse'>
        Give it a rest, idiot!
    </tmpl_if>

This indicator shows that the plugin detected abuse (see C<max_abuse>
plugin's argument for details).

=head2 C<plug_forgot_password_stage_emailed>

    <tmpl_if name='plug_forgot_password_stage_emailed'>
        Sent ya an email, dude!
    </tmpl_if>

This indicator turns on when the plugin successfully sent the user
an email containing reset pass link.

=head2 C<plug_forgot_password_stage_code_invalid>

    <tmpl_if name='plug_forgot_password_stage_code_invalid'>
        Your reset code has expired, buddy. Hurry up, next time!
    </tmpl_if>

This indicator is active when the plugin can't find the code the user
is giving it. Under natural circumstances, this will only occur when
the code has expired.

=head2 C<plug_forgot_password_stage_change_pass_ask>

    <tmpl_if name='plug_forgot_password_stage_change_pass_ask'>
        What's the new pass you want, buddy?
    </tmpl_if>

This indicator turns on when the form asking the user for the new password
is active.

=head2 C<plug_forgot_password_stage_code_bad_pass_length>

    <tmpl_if name='plug_forgot_password_stage_code_bad_pass_length'>
        That pass's too short, dude.
    </tmpl_if>

This indicator signals that the user attempted to use too short of a new
password (the length is controlled with the C<min_pass> plugin's argument).

=head2 C<plug_forgot_password_stage_code_bad_pass_copy>

    <tmpl_if name='plug_forgot_password_stage_code_bad_pass_copy'>
        It's really hard to type the same thing twice, ain't it?
    </tmpl_if>

This indicator turns on if the user did not retype the new password
correctly.

=head2 C<plug_forgot_password_stage_change_pass_done>

    <tmpl_if name='plug_forgot_password_stage_change_pass_done'>
        Well, looks like you're all done with reseting your pass and what not.
    </tmpl_if>

This indicator shows that the final stage of plugin's run has been reached;
i.e. the user has successfully reset the password and can go on with
their other business.

=head1 OUTPUT

The plugin generates a whole bunch of various output; what's below should
cover all the bases:

=head2 Default Email Template

    <h2>Password Reset</h2>

    <p>Hello. Someone (possibly you) requested a password reset. If that
    was you, please follow this link to complete the action:
    <a href="<tmpl_var escape='html' name='link'>"><tmpl_var escape='html'
    name='link'></a></p>

    <p>If you did not request anything, simply ignore this email.</p>

You can change this using C<email_template> argument. When using your
own, use C<< <tmpl_var escape='html' name='link'> >> to insert the
link the user needs to follow.

=head2 "Ask Login" Form Template

    <form action="" method="POST" id="plug_forgot_password_form">
    <div>
        <p>Please enter your login into the form below and an email with
            further instructions will be sent to you.</p>

        <input type="hidden" name="page" value="<tmpl_var escape='html'
            name='page'>">
        <input type="hidden" name="pulfp_ask_link" value="1">
        <tmpl_if name='error'>
            <p class="error"><tmpl_var escape='html' name='error'></p>
        </tmpl_if>

        <label for="pulfp_login">Your login: </label
        ><input type="text"
            class="input_text"
            name="pulfp_login"
            id="pulfp_login">

        <input type="submit"
            class="input_submit"
            value="Send password">
    </div>
    </form>

This is the form that asks the user for their login in order to reset
the password. Submit button is plugin's default code, you can control
it with the C<button_send_link> plugin's argument.

=head2 "New Password" Form Template

    <form action="" method="POST" id="plug_forgot_password_new_pass_form">
    <div>