Catalyst-Authentication-Store-Htpasswd-1.005

[catagits/Catalyst-Authentication-Store-Htpasswd.git] / README.pod

diff --git a/README.pod b/README.pod
new file mode 100644 (file)
index 0000000..5c8a192
--- /dev/null
+++ b/README.pod
@@ -0,0 +1,156 @@
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+Catalyst::Authentication::Store::Htpasswd - Authen::Htpasswd based user storage/authentication
+
+=head1 VERSION
+
+version 1.005
+
+=head1 SYNOPSIS
+
+    use Catalyst qw/
+      Authentication
+    /;
+
+    __PACKAGE__->config(
+        authentication => {
+            default_realm => 'test',
+            realms => {
+                test => {
+                    credential => {
+                        class          => 'Password',
+                        password_field => 'password',
+                        password_type  => 'self_check',
+                    },
+                    store => {
+                        class => 'Htpasswd',
+                        file => 'htpasswd',
+                    },
+                },
+            },
+        },   
+    );
+
+    sub login : Global {
+        my ( $self, $c ) = @_;
+
+        $c->authenticate({ username => $c->req->param("login"), password => $c->req->param("password") });
+    }
+
+=head1 DESCRIPTION
+
+This plugin uses L<Authen::Htpasswd> to let your application use C<<.htpasswd>>
+files for it's authentication storage.
+
+=head1 METHODS
+
+=head2 new
+
+Simple constructor, dies if the htpassword file can't be found
+
+=head2 find_user
+
+Looks up the user, and returns a Catalyst::Authentication::Store::Htpasswd::User object.
+
+=head2 user_supports
+
+Delegates to L<Catalyst::Authentication::Store::Htpasswd::User->user_supports|Catalyst::Authentication::Store::Htpasswd::User#user_supports>
+
+=head2 from_session
+
+Delegates the user lookup to C<< find_user >>
+
+=head1 CONFIGURATION
+
+=head2 file
+
+The path to the htpasswd file. If the path starts with a slash, then it is assumed to be a fully
+qualified path, otherwise the path is fed through C<< $c->path_to >> and so normalised to the 
+application root.
+
+Alternatively, it is possible to pass in an L<Authen::Htpasswd> object here, and this will be
+used as the htpasswd file.
+
+=head2 user_class
+
+Change the user class which this store returns. Defaults to L<Catalyst::Authentication::Store::Htpasswd::User>.
+This can be used to add additional functionality to the user class by sub-classing it, but will not normally be
+needed.
+
+=head2 user_field
+
+Change the field that the username is found in in the information passed into the call to C<< $c->authenticate() >>.
+
+This defaults to I< username >, and generally you should be able to use the module as shown in the synopsis, however
+if you need a different field name then this setting can change the default.
+
+Example:
+
+    __PACKAGE__->config( authentication => { realms => { test => {
+                    store => {
+                        class => 'Htpasswd',
+                        user_field => 'email_address',
+                    },
+    }}});
+    # Later in your code
+    $c->authenticate({ email_address => $c->req->param("email"), password => $c->req->param("password") });
+
+=head1 SEE ALSO
+
+L<Authen::Htpasswd>.
+
+=head1 SUPPORT
+
+Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Authentication-Store-Htpasswd>
+(or L<bug-Catalyst-Authentication-Store-Htpasswd@rt.cpan.org|mailto:bug-Catalyst-Authentication-Store-Htpasswd@rt.cpan.org>).
+
+There is also a mailing list available for users of this distribution, at
+L<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst>.
+
+There is also an irc channel available for users of this distribution, at
+L<C<#catalyst> on C<irc.perl.org>|irc://irc.perl.org/#catalyst>.
+
+=head1 AUTHOR
+
+יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
+
+=head1 CONTRIBUTORS
+
+=for stopwords David Kamholz Tomas Doran Karen Etheridge Tom Bloor Ilmari Vacklin
+
+=over 4
+
+=item *
+
+David Kamholz <dkamholz@cpan.org>
+
+=item *
+
+Tomas Doran <bobtfish@bobtfish.net>
+
+=item *
+
+Karen Etheridge <ether@cpan.org>
+
+=item *
+
+Tom Bloor <t.bloor@shadowcat.co.uk>
+
+=item *
+
+Ilmari Vacklin <ilmari.vacklin@cs.helsinki.fi>
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2005 by יובל קוג'מן (Yuval Kogman).
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut