NAME

Catalyst::Authentication::Store::Jifty::DBI - A storage class for Catalyst Authentication using Jifty::DBI

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         => 'Jifty::DBI',
            user_class    => 'MyDB::User',
            role_relation => [qw( roles role_map role )],
          },
        },
      },
    };

    sub login : Global {
      my ($self, $c) = @_;

      $c->authenticate({
        username => $c->req->params->{username},
        password => $c->req->params->{password},
        status   => [ 'registered', 'loggedin', 'active' ],
      });
    }

    sub edit : Path {
      my ($self, $c) = @_;

      # verify a role
      if ( $c->check_user_roles('editor') ) {
        # do some editorial things
      }
    }

DESCRIPTION

This Jifty::DBI store class is a rough port of Catalyst::Authentication::Store::DBIx::Class. See Catalyst::Authentication::Store::DBIx::Class and Catalyst::Plugin::Authentication for what I'm too lazy to explain.

CONFIGURATION

Almost the same as ::Store::DBIx::Class, with a few changes. See SYNOPSIS for common usage. To activate this authentication store, set class element in the store config to 'Jifty::DBI'.

    __PACKAGE__->config->{authentication} = {
      default_realm => 'members',
      realms => {
        members => {
          credential => {
            # ...
          },
          store => {
            class         => 'Jifty::DBI',
            user_class    => 'MyDB::User',
            role_relation => [qw( roles link_to_role role )],
          },
        },
      },
    };

There are several configurable options:

class

should be set to 'Jifty::DBI' to activate this store.

user_class

must contain the moniker (the class name which would be passed to $c->model(...) ) to retrieve user information. You can set either the one for a record or the one for a collection (both of which would be converted internally). If you dare, you also can set record_class and/or collection_class as you wish.

role_column

If your role information is stored in the same table as the rest of your user information, set this to show which column contains your role information. The value in this column is expected to be a series of role names separated by some combination of white spaces, commas, or pipe characters.

role_relation

NOTE: this option is different from the one of Catalyst::Authentication::Store::DBIx::Class.

If your role information is stored in a separate table, set this to an array reference of the method chain to retrieve role information from a user record. That means: if your user class has a 'roles' collection, and each of whose record is linked to your role class via 'link_to_role' column, and your role class has a 'role' column, then set this as shown above.

use_userdata_from_session

If this flag is set to true, the data for the user object is retrieved from a restored hash (instead of the user table in the database).

USAGE

Normally, all you need to do is pass enough pairs of column/value to $c->authenticate() to find an (rather, the only one) appropriate user. All the conditions should be satisfied ("and" conditions).

  if (
    $c->authenticate({
      username => $c->req->params->{username},
      password => $c->req->params->{password},
      status   => [ 'registered', 'active', 'loggedin' ],
    })
  ) {
    # ... authenticated user code here
  }

If you want finer control, namely when you want "or" conditions, you can pass either of the extra (advanced) arguments. These advanced arguments should be placed under the "jifty_dbi" key for this purpose.

You can put arbitrary arguments (an array reference of hash references) under the "limit_args", each of which would then be passed to $user_collection->limit(). Use "subclause" for "or" conditions. See Jifty::Manual::Cookbook for details.

  if (
    # this makes "WHERE (username = ?) or (email = ?)" kind of clause

    $c->authenticate({
      password  => $c->req->params->{password},
      jifty_dbi => {
        limit_args => [{
          column    => 'username',
          value     => $c->req->params->{username},
          subclause => 'or_condition',
        },
        {
          column    => 'email',
          value     => $c->req->params->{email},
          subclause => 'or_condition',
        }],
      }
    })
  ) {
    # ... authenticated user code here
  }

If you want much finer control, you can pass pre-configured collection object.

  my $collection = $c->model('MyDB::User');

  # do whatever you want with this $collection

  if (
    $c->authenticate({
      password  => $c->req->params->{password},
      jifty_dbi => { collection => $collection },
    })
  ) {
    # ... authenticated user code here
  }

NOTE: When multiple users are found, $c->user holds the "first" one (retrieved by $collection->first).

METHODS

Most of these are used internally while authenticating/authorizing and usually you don't need to care.

new

creates a store object.

find_user

finds a user with provided auth information.

from_session

revives a user from the session.

for_session

stores a user for the session.

user_supports

shows what this store supports.

auto_create_user

will be called if you set the realm's "auto_update_user" setting.

auto_update_user

will be called if you set the realm's "auto_create_user" setting.

SEE ALSO

Catalyst::Plugin::Authentication, Catalyst::Authentication::Store::DBIx::Class

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kenichi Ishigaki.

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

cpanm Catalyst::Authentication::Store::Jifty::DBI

perl -MCPAN -e shell
install Catalyst::Authentication::Store::Jifty::DBI