[Catalyst-commits] r7065 - in
trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class: .
lib/Catalyst/Plugin/Authentication/Store/DBIx
bricas at dev.catalyst.perl.org
bricas at dev.catalyst.perl.org
Fri Oct 26 02:32:56 GMT 2007
Author: bricas
Date: 2007-10-26 02:32:55 +0100 (Fri, 26 Oct 2007)
New Revision: 7065
Removed:
trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/README
Modified:
trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/Makefile.PL
trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm
Log:
pod stuff
Modified: trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/Makefile.PL
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/Makefile.PL 2007-10-26 01:31:49 UTC (rev 7064)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/Makefile.PL 2007-10-26 01:32:55 UTC (rev 7065)
@@ -1,12 +1,19 @@
use inc::Module::Install 0.67;
+if( -e 'MANIFEST.SKIP' ) {
+ system( 'pod2text lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm > README' );
+}
+
name 'Catalyst-Plugin-Authentication-Store-DBIx-Class';
all_from 'lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm';
+perl_version '5.8.1';
+
requires 'Catalyst::Runtime';
requires 'Catalyst::Plugin::Authentication';
-requires 'Test::More';
+test_requires 'Test::More';
+
auto_install;
WriteAll;
Deleted: trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/README
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/README 2007-10-26 01:31:49 UTC (rev 7064)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/README 2007-10-26 01:32:55 UTC (rev 7065)
@@ -1,332 +0,0 @@
-NAME
- Catalyst::Plugin::Authentication::Store::DBIx::Class - A storage class
- for Catalyst Authentication using DBIx::Class
-
-VERSION
- This documentation refers to version 0.10.
-
-SYNOPSIS
- use Catalyst qw/
- Authentication
- Authorization::Roles/;
-
- __PACKAGE__->config->{authentication} =
- {
- default_realm => 'members',
- realms => {
- members => {
- credential => {
- class => 'Password',
- password_field => 'password',
- password_type => 'clear'
- },
- store => {
- class => 'DBIx::Class',
- user_class => 'MyApp::Users',
- id_field => 'user_id',
- role_relation => 'roles',
- role_field => 'rolename',
- }
- }
- }
- };
-
- # Log a user in:
-
- sub login : Global {
- my ( $self, $c ) = @_;
-
- $c->authenticate({
- username => $c->req->params->username,
- password => $c->req->params->password,
- status => [ 'registered', 'loggedin', 'active']
- }))
- }
-
- # verify a role
-
- if ( $c->check_user_roles( 'editor' ) ) {
- # do editor stuff
- }
-
-DESCRIPTION
- The Catalyst::Plugin::Authentication::Store::DBIx::Class class provides
- access to authentication information stored in a database via
- DBIx::Class.
-
-CONFIGURATION
- The DBIx::Class authentication store is activated by setting the store
- config's class element to DBIx::Class as shown above. See the
- Catalyst::Plugin::Authentication documentation for more details on
- configuring the store.
-
- The DBIx::Class storage module has several configuration options
-
- __PACKAGE__->config->{authentication} =
- {
- default_realm => 'members',
- realms => {
- members => {
- credential => {
- # ...
- },
- store => {
- class => 'DBIx::Class',
- user_class => 'MyApp::Users',
- id_field => 'user_id',
- role_relation => 'roles',
- role_field => 'rolename',
- ignore_fields_in_find => [ 'remote_name' ]
- }
- }
- }
- };
-
- class
- Class is part of the core Catalyst::Authentication::Plugin module,
- it contains the class name of the store to be used.
-
- user_class
- Contains the class name (as passed to $c->model()) of the
- DBIx::Class schema to use as the source for user information. This
- config item is REQUIRED.
-
- id_field
- Contains the field name containing the unique identifier for a user.
- This is used when storing and retrieving a user from the session.
- The value in this field should correspond to a single user in the
- database. Defaults to 'id'.
-
- role_column
- If your role information is stored in the same table as the rest of
- your user information, this item tells the module which field
- contains your role information. The DBIx::Class authentication store
- expects the data in this field to be a series of role names
- separated by some combination of spaces, commas or pipe characters.
-
- role_relation
- If your role information is stored in a separate table, this is the
- name of the relation that will lead to the roles the user is in. If
- this is specified then a role_field is also required. Also when
- using this method it is expected that your role table will return
- one row for each role the user is in.
-
- role_field
- This is the name of the field in the role table that contains the
- string identifying the role.
-
- ignore_fields_in_find
- This item is an array containing fields that may be passed to the
- $c->authenticate() routine (and therefore find_user in the storage
- class), but which should be ignored when creating the DBIx::Class
- search to retrieve a user. This makes it possible to avoid problems
- when a credential requires an authinfo element whose name overlaps
- with a column name in your users table. If this doesn't make sense
- to you, you probably don't need it.
-
- store_user_class
- This allows you to override the authentication user class that the
- DBIx::Class store module uses to perform it's work. Most of the work
- done in this module is actually done by the user class,
- Catalyst::Plugin::Authentication::Store::DBIx::Class::User, so
- overriding this doesn't make much sense unless you are using your
- own class to extend the functionality of the existing class. Chances
- are you do not want to set this.
-
-USAGE
- The Catalyst::Plugin::Authentication::Store::DBIx::Class storage module
- is not called directly from application code. You interface with it
- through the $c->authenticate() call.
-
- There are three methods you can use to retrieve information from the
- DBIx::Class storage module. They are Simple retrieval, and the advanced
- retrieval methods Searchargs and Resultset.
-
- Simple Retrieval
- The first, and most common, method is simple retrieval. As it's name
- implies simple retrieval allows you to simply to provide the column =>
- value pairs that should be used to locate the user in question. An
- example of this usage is below:
-
- if ($c->authenticate({
- username => $c->req->params->{'username'},
- password => $c->req->params->{'password'},
- status => [ 'registered', 'active', 'loggedin']
- })) {
-
- # ... authenticated user code here
- }
-
- The above example would attempt to retrieve a user whose username column
- matched the username provided, and whose status column matched one of
- the values provided. These name => value pairs are used more or less
- directly in the DBIx::Class' search() routine, so in most cases, you can
- use DBIx::Class syntax to retrieve the user according to whatever rules
- you have.
-
- NOTE: Because the password in most cases is encrypted - it is not used
- directly but it's encryption and comparison with the value provided is
- usually handled by the Password Credential. Part of the Password
- Credential's behavior is to remove the password argument from the
- authinfo that is passed to the storage module. See
- Catalyst::Plugin::Authentication::Credential::Password.
-
- One thing you need to know about this retrieval method is that the name
- portion of the pair is checked against the user class' column list.
- Pairs are only used if a matching column is found. Other pairs will be
- ignored. This means that you can only provide simple name-value pairs,
- and that some more advanced DBIx::Class constructs, such as '-or',
- '-and', etc. are in most cases not possible using this method. For
- queries that require this level of functionality, see the 'searchargs'
- method below.
-
- Advanced Retrieval
- The Searchargs and Resultset retrieval methods are used when more
- advanced features of the underlying DBIx::Class schema are required.
- These methods provide a direct interface with the DBIx::Class schema and
- therefore require a better understanding of the DBIx::Class module.
-
- The dbix_class key
- Since the format of these arguments are often complex, they are not keys
- in the base authinfo hash. Instead, both of these arguments are placed
- within a hash attached to the store-specific 'dbix_class' key in the
- base $authinfo hash. When the DBIx::Class authentication store sees the
- 'dbix_class' key in the passed authinfo hash, all the other information
- in the authinfo hash is ignored and only the values within the
- 'dbix_class' hash are used as though they were passed directly within
- the authinfo hash. In other words, if 'dbix_class' is present, it
- replaces the authinfo hash for processing purposes.
-
- The 'dbix_class' hash can be used to directly pass arguments to the
- DBIx::Class authentication store. Reasons to do this are to avoid
- credential modification of the authinfo hash, or to avoid overlap
- between credential and store key names. It's a good idea to avoid using
- it in this way unless you are sure you have an overlap/modification
- issue. However, the two advanced retrieval methods, searchargs and
- resultset, require it's use, as they are only processed as part of the
- 'dbix_class' hash
-
- Searchargs
- The searchargs method of retrieval allows you to specify an arrayref
- containing the two arguments to the search() method from
- DBIx::Class::ResultSet. If provided, all other args are ignored, and
- the search args provided are used directly to locate the user. An
- example will probably make more sense:
-
- if ($c->authenticate(
- {
- password => $password,
- 'dbix_class' =>
- {
- searchargs = [ { -or => [ username => $username,
- email => $email,
- clientid => $clientid ]
- },
- { prefetch => qw/ preferences / }
- ]
- }
- } ) )
- {
- # do successful authentication actions here.
- }
-
- The above would allow authentication based on any of the three items
- - username, email or clientid and would prefetch the data related to
- that user from the preferences table. The searchargs array is passed
- directly to the search() method associated with the user_class.
-
- Resultset
- The resultset method of retrieval allows you to directly specify a
- resultset to be used for user retrieval. This allows you to create a
- resultset within your login action and use it for retrieving the
- user. A simple example:
-
- my $rs = $c->model('MyApp::User')->search({ email => $c->request->params->{'email'} });
- ... # further $rs adjustments
-
- if ($c->authenticate({
- password => $password,
- 'dbix_class' => { resultset = $rs }
- })) {
- # do successful authentication actions here.
- }
-
- Be aware that the resultset method will not verify that you are
- passing a resultset that is attached to the same user_class as
- specified in the config.
-
- NOTE: All of these methods of user retrieval, including the
- resultset method, consider the first row returned to be the matching
- user. In most cases there will be only one matching row, but it is
- easy to produce multiple rows, especially when using the advanced
- retrieval methods. Remember, what you get when you use this module
- is what you would get when calling search(...)->first;
-
- NOTE ALSO: The user info used to save the user to the session and to
- retrieve it is the same regardless of what method of retrieval was
- used. In short, the value in the id field (see 'id_field' config
- item) is used to retrieve the user from the database upon restoring
- from the session. When the DBIx::Class storage module does this, it
- does so by doing a simple search using the id field. In other words,
- it will not use the same arguments you used to request the user
- initially. This is especially important to those using the advanced
- methods of user retrieval. If you need more complicated logic when
- reviving the user from the session, you will most likely want to
- subclass the
- Catalyst::Plugin::Authentication::Store::DBIx::Class::User class and
- provide your own for_session and from_session routines.
-
-METHODS
- There are no publicly exported routines in the DBIx::Class
- authentication store (or indeed in most authentication stores) However,
- below is a description of the routines required by
- Catalyst::Plugin::Authentication for all authentication stores. Please
- see the documentation for Catalyst::Plugin::Authentication::Internals
- for more information.
-
- new ( $config, $app )
- Constructs a new store object.
-
- find_user ( $authinfo, $c )
- Finds a user using the information provided in the $authinfo hashref
- and returns the user, or undef on failure; This is usually called
- from the Credential. This translates directly to a call to
- Catalyst::Plugin::Authentication::Store::DBIx::Class::User's load()
- method.
-
- for_session ( $c, $user )
- Prepares a user to be stored in the session. Currently returns the
- value of the user's id field - (as indicated by the 'id_field'
- config element)
-
- from_session ( $c, $frozenuser)
- Revives a user from the session based on the info provided in
- $frozenuser. Currently treats $frozenuser as an id and retrieves a
- user with a matching id.
-
- user_supports
- Provides information about what the user object supports.
-
-NOTES
- As of the current release, session storage consists of simply storing
- the user's id in the session, and then using that same id to re-retrieve
- the users information from the database upon restoration from the
- session. More dynamic storage of user information in the session is
- intended for a future release.
-
-BUGS AND LIMITATIONS
- None known currently, please email the author if you find any.
-
-SEE ALSO
- Catalyst::Plugin::Authentication,
- Catalyst::Plugin::Authentication::Internals, and
- Catalyst::Plugin::Authorization::Roles
-
-AUTHOR
- Jason Kuri (jayk at cpan.org)
-
-LICENSE
- Copyright (c) 2007 the aforementioned authors. All rights reserved. This
- program is free software; you can redistribute it and/or modify it under
- the same terms as Perl itself.
-
Modified: trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm 2007-10-26 01:31:49 UTC (rev 7064)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIx-Class/lib/Catalyst/Plugin/Authentication/Store/DBIx/Class.pm 2007-10-26 01:32:55 UTC (rev 7065)
@@ -375,7 +375,6 @@
=back
-
=head1 METHODS
There are no publicly exported routines in the DBIx::Class authentication
@@ -384,39 +383,41 @@
for all authentication stores. Please see the documentation for
L<Catalyst::Plugin::Authentication::Internals> for more information.
-=over 4
+=head2 new( $config, $app )
-=item new ( $config, $app )
-
Constructs a new store object.
-=item find_user ( $authinfo, $c )
+=head2 find_user( $authinfo, $c )
Finds a user using the information provided in the $authinfo hashref and
returns the user, or undef on failure; This is usually called from the
Credential. This translates directly to a call to
L<Catalyst::Plugin::Authentication::Store::DBIx::Class::User>'s load() method.
-=item for_session ( $c, $user )
+=head2 for_session( $c, $user )
Prepares a user to be stored in the session. Currently returns the value of
the user's id field - (as indicated by the 'id_field' config element)
-=item from_session ( $c, $frozenuser)
+=head2 from_session( $c, $frozenuser)
Revives a user from the session based on the info provided in $frozenuser.
Currently treats $frozenuser as an id and retrieves a user with a matching id.
-=item user_supports
+=head2 user_supports( )
Provides information about what the user object supports.
-=item auto_update_user
+=head2 auto_update_user( $authinfo, $c, $res )
-=item auto_create_user
+This method is called if the realm's auto_update_user setting is true. It
+will delegate to the user object's C<auto_update> method.
-=back
+=head2 auto_create_user( $authinfo, $c )
+This method is called if the realm's auto_create_user setting is true. It
+will delegate to the user class' (resultset) C<auto_create> method.
+
=head1 NOTES
As of the current release, session storage consists of simply storing the user's
More information about the Catalyst-commits
mailing list