/ 
App-ZofCMS-Plugin-RandomPasswordGenerator-0.0103
/ App::ZofCMS::Plugin::RandomPasswordGenerator

NAME

App::ZofCMS::Plugin::RandomPasswordGenerator - easily generate random passwords with an option to use md5_hex from Digest::MD5 on them

SYNOPSIS

# simple usage example; config values are plugin's defaults

plugins => [ qw/RandomPasswordGenerator/ ],
plug_random_password_generator => {
    length   => 8,
    chars    => [ 0..9, 'a'..'z', 'A'..'Z' ],
    cell     => 'd',
    key      => 'random_pass',
    md5_hex  => 0,
    pass_num => 1,
},

# generated password is now a string in $t->{d}{random_pass}
# where $t is ZofCMS Template hashref

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to generate one or several random passwords and optionally use md5_hex() from Digest::MD5 on them.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

Make sure to read FORMAT OF VALUES FOR GENERATED PASSWORDS section at the end of this document.

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

plugins => [ qw/RandomPasswordGenerator/ ],

Self-explanatory: you need to include the plugin in the list of plugins to run.

plug_random_password_generator

plug_random_password_generator => {
    length   => 8,
    chars    => [ 0..9, 'a'..'z', 'A'..'Z' ],
    cell     => 'd',
    key      => 'random_pass',
    md5_hex  => 0,
    pass_num => 1,
},

plug_random_password_generator => sub {
    my ( $t, $q, $config ) = @_;
    return {
        length   => 8,
        chars    => [ 0..9, 'a'..'z', 'A'..'Z' ],
        cell     => 'd',
        key      => 'random_pass',
        md5_hex  => 0,
        pass_num => 1,
    }
},

Mandatory. The plugin won't run unless plug_random_password_generator first-level key is present. Takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_random_password_generator as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. To run the plugin with all the defaults specify an empty hashref as a value. The plug_random_password_generator key can be set in either (or both) Main Config File and ZofCMS Template; if set in both, the hashref keys that are set in ZofCMS Template will override the ones that are set in Main Config File. Possible keys/values of the hashref are as follows:

length

plug_random_password_generator => {
    length   => 8,
}

Optional. Takes a positive integer as a value. Specifies the length - in characters - of password(s) to generate. Defaults to: 8

chars

plug_random_password_generator => {
    chars    => [ 0..9, 'a'..'z', 'A'..'Z' ],
}

Optional. Takes an arrayref as a value. Elements of this arrayref must be characters; these characters specify the set of characters to be used in the generated password. Defaults to: [ 0..9, 'a'..'z', 'A'..'Z' ]

cell

plug_random_password_generator => {
    cell     => 'd',
}

Optional. Takes a string specifying the name of the first-level ZofCMS Template key into which to create key key (see below) and place the results. The key must be a hashref (or undef, in which case it will be autovivified); why? see key argument below. Defaults to: d

key

plug_random_password_generator => {
    key      => 'random_pass',
}

Optional. Takes a string specifying the name of the ZofCMS Template key in hashref specified be cell (see above) into which to place the results. In other words, if cell is set to d and key is set to random_pass then generated password(s) will be found in $t->{d}{random_pass} where $t is ZofCMS Template hashref. Defaults to: random_pass

md5_hex

plug_random_password_generator => {
    md5_hex  => 0,
}

Optional. Takes either true or false values. When set to a true value, the plugin will also generate string that is made from calling md5_hex() from Digest::MD5 on the generated password. See FORMAT OF VALUES FOR GENERATED PASSWORDS section below. Defaults to: 0

pass_num

plug_random_password_generator => {
    pass_num => 1,
}

Optional. Takes a positive integer as a value. Specifies the number of passwords to generate. See FORMAT OF VALUES FOR GENERATED PASSWORDS section below. Defaults to: 1

FORMAT OF VALUES FOR GENERATED PASSWORDS

Examples below assume that cell argument is set to d and key argument is set to random_pass (those are their defaults). The $VAR is ZofCMS Template hashref, other keys of this hashref were removed for brevity.

# all defaults
$VAR1 = {
    'd' => {
        'random_pass' => 'ETKSeRJS',
...

# md5_hex option is set to a true value, the rest are defaults
$VAR1 = {
    'd' => {
        'random_pass' => [
                            '3b6SY9LY',                         # generated password
                            '6e28112de1ff183966248d78a4aa1d7b'  # md5_hex() ran on it
                         ]
...

# pass_num is set to 2, the rest are defaults
$VAR1 = {
    'd' => {
        'random_pass' => [
                            'oqdQmwZ5', # first password
                            'NwzRv6q8'  # second password
                         ],
...

# pass_num is set to 2 and md5_hex is set to a true value
$VAR1 = {
    'd' => {
        'random_pass' => [
            [
                '9itPzasC',                             # first password
                '5f29eb2cf6dbccc048faa9666187ac22'      # md5_hex() ran on it
            ],
            [
                'ytRRXqtq',                            # second password
                '81a6a7836e1d08ea2ae1c43c9dbef941'     # md5_hex() ran on it
            ]
        ]
...

There are four different types of values (depending on settings) that plugin will generate. In the following text, word "output value" will be used to refer to the value of the key refered to by key and cell plugin's arguments; in other words, if cell is set to d and key is set to random_pass then "output value" will be the value of $t->{d}{random_pass} where $t is ZofCMS Template hashref.

With all the defaults output value will be a single string that is the generated password.

If md5_hex option is set to a true value, instead of that string the plugin will generate an arrayref first element of which will be the generated password and second element will be the string generated by running md5_hex() on that password.

If pass_num is set to a number greater than 1 then each generated password will be an element of an arrayref instead and output value will be an arrayref.

See four examples in the beginning of this section if you are still confused.

AUTHOR

'Zoffix, <'zoffix at cpan.org'> (http://zoffix.com/, http://haslayout.net/, http://zofdesign.com/)

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-randompasswordgenerator at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-RandomPasswordGenerator. I will be notified, and then you'll 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 App::ZofCMS::Plugin::RandomPasswordGenerator

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 'Zoffix, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.