=head1 VERSION
-This documentation refers to version 0.01.
+This documentation refers to version 0.02.
=head1 SYNOPSIS
role_relation => 'roles',
role_field => 'rolename',
}
- }
+ }
}
};
my ( $self, $c ) = @_;
$c->authenticate({
- username => $c->req->params->username,
- password => $c->req->params->password,
- status => [ 'registered', 'loggedin', 'active' ]
- }))
+ username => $c->req->params->username,
+ password => $c->req->params->password,
+ status => [ 'registered', 'loggedin', 'active']
+ }))
}
# verify a role
=head1 CONFIGURATION
The DBIx::Class authentication store is activated by setting the store
-config's class element to DBIx::Class as shown above. See the
+config's B<class> element to DBIx::Class as shown above. See the
L<Catalyst::Plugin::Authentication> documentation for more details on
configuring the store.
=item ignore_fields_in_find
-This item is an array containing fields that may be passed to the
-find_user routine, 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.
+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.
=item store_user_class
is not called directly from application code. You interface with it
through the $c->authenticate() call.
-... documentation fairy fell asleep here ...
+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.
+
+=head2 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 L<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.
+
+=head2 Advanced Retrieval
+
+The Searchargs and Resultset retrieval methods are used when more advanced
+features of the underlying L<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.
+
+=head3 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, B<searchargs> and B<resultset>, require it's use, as they
+are only processed as part of the 'dbix_class' hash
+
+=over 4
+
+=item Searchargs
+
+The B<searchargs> method of retrieval allows you to specify an arrayref containing
+the two arguments to the search() method from L<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.
+
+=item Resultset
+
+The B<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 L<Catalyst::Plugin::Authentication::Store::DBIx::Class::User> class
+and provide your own for_session and from_session routines.
+
+=back
=head1 METHODS
=item new ( $config, $app )
-Constructs a new store object, which uses the user element of the supplied config
-hash ref as it's backing structure.
+Constructs a new store object.
=item find_user ( $authinfo, $c )
-Finds a user using the information provided in the $authinfo hashref and returns
-the user, or undef on failure; This translates directly to a call to
+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 )
-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)
+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)
-Revives a user from the session based on the info provided in $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
Jason Kuri (jayk@cpan.org)
-=head1 LICENCE
+=head1 LICENSE
-Copyright (c) 2005 the aforementioned authors. All rights
+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.
}
}
-sub obj {
+sub get_object {
my $self = shift;
- return $self->get_object;
+ return $self->_user;
}
-sub get_object {
+sub obj {
my $self = shift;
- return $self->_user;
+ return $self->get_object;
}
sub AUTOLOAD {
=head1 NAME
-Catalyst::Plugin::Authentication::Store::DBIx::Class::User - A class to ...
+Catalyst::Plugin::Authentication::Store::DBIx::Class::User - The backing user
+class for the Catalyst::Plugin::Authentication::Store::DBIx::Class storage
+module.
=head1 VERSION
-This documentation refers to version 0.01.
+This documentation refers to version 0.02.
=head1 SYNOPSIS
-Internal - not used directly. use Catalyst::Plugin::Authentication::Store::DBIx::Class::User;
-
+Internal - not used directly, please see
+L<Catalyst::Plugin::Authentication::Store::DBIx::Class> for details on how to
+use this module. If you need more information than is present there, read the
+source.
=head1 DESCRIPTION
-The Catalyst::Plugin::Authentication::Store::DBIx::Class::User class implements ...
+The Catalyst::Plugin::Authentication::Store::DBIx::Class::User class implements user storage
+connected to an underlying DBIx::Class schema object.
=head1 SUBROUTINES / METHODS
-=head2 new (constructor)
-
-Parameters:
- class
- authinfo
- config
- c
- lazyload
-
-Insert description of constructor here...
+=head2 new
-=head2 load_user (method)
+Constructor.
-Parameters:
- authinfo
- c
+=head2 load_user ( $authinfo, $c )
-Insert description of method here...
+Retrieves a user from storage using the information provided in $authinfo.
-=head2 supported_features (method)
+=head2 supported_features
-Parameters:
- none
-
-Insert description of method here...
+Indicates the features supported by this class. These are currently Roles and Session.
=head2 roles
-Parameters:
- none
-
-Insert description of subroutine here...
+Returns an array of roles associated with this user, if roles are configured for this user class.
=head2 for_session
-Parameters:
- none
+Returns a serialized user for storage in the session. Currently, this is the value of the field
+specified by the 'id_field' config variable.
-Insert description of subroutine here...
+=head2 get ( $fieldname )
-=head2 get (method)
+Returns the value of $fieldname for the user in question. Roughly translates to a call to
+the DBIx::Class::Row's get_column( $fieldname ) routine.
-Parameters:
- field
+=head2 get_object
-Insert description of method here...
+Retrieves the DBIx::Class object that corresponds to this user
=head2 obj (method)
-Parameters:
- none
-
-Insert description of method here...
-
-=head2 get_object (method)
-
-Parameters:
- none
-
-Insert description of method here...
-
-=head2 AUTOLOAD (method)
-
-Parameters:
- none
-
-Insert description of method here...
-
-=head1 DEPENDENCIES
-
-Modules used, version dependencies, core yes/no
-
-strict
-
-warnings
-
-=head1 NOTES
-
-...
+Synonym for get_object
=head1 BUGS AND LIMITATIONS
Jason Kuri (jk@domain.tld)
-=head1 LICENCE
-
-Copyright 2006 by Jason Kuri.
+=head1 LICENSE
-This software is free. It is licensed under the same terms as Perl itself.
+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.
=cut
projects / catagits/Catalyst-Authentication-Store-DBIx-Class.git / commitdiff