lib/Catalyst/Authentication/User.pm

   1 package Catalyst::Authentication::User;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/Class::Accessor::Fast/;
   6
   7 ## auth_realm is the realm this user came from.
   8 BEGIN {
   9     __PACKAGE__->mk_accessors(qw/auth_realm store/);
  10 }
  11
  12 ## THIS IS NOT A COMPLETE CLASS! it is intended to provide base functionality only.
  13 ## translation - it won't work if you try to use it directly.
  14
  15 ## chances are you want to override this.
  16 sub id { shift->get('id'); }
  17
  18 ## this relies on 'supported_features' being implemented by the subclass..
  19 ## but it is not an error if it is not.  it just means you support nothing.
  20 ## nihilist user objects are welcome here.
  21 sub supports {
  22     my ( $self, @spec ) = @_;
  23
  24     my $cursor = undef;
  25     if ($self->can('supported_features')) {
  26         $cursor = $self->supported_features;
  27
  28         # traverse the feature list,
  29         for (@spec) {
  30             #die "bad feature spec: @spec" if ref($cursor) ne "HASH";
  31             return if ref($cursor) ne "HASH";
  32
  33             $cursor = $cursor->{$_};
  34         }
  35     }
  36
  37     return $cursor;
  38 }
  39
  40 ## REQUIRED.
  41 ## get should return the value of the field specified as it's single argument from the underlying
  42 ## user object.  This is here to provide a simple, standard way of accessing individual elements of a user
  43 ## object - ensuring no overlap between C::P::A::User methods and actual fieldnames.
  44 ## this is not the most effecient method, since it uses introspection.  If you have an underlying object
  45 ## you most likely want to write this yourself.
  46 sub get {
  47     my ($self, $field) = @_;
  48
  49     my $object;
  50     if ($object = $self->get_object and $object->can($field)) {
  51         return $object->$field();
  52     } else {
  53         return undef;
  54     }
  55 }
  56
  57 ## REQUIRED.
  58 ## get_object should return the underlying user object.  This is for when more advanced uses of the
  59 ## user is required.  Modifications to the existing user, etc.  Changes in the object returned
  60 ## by this routine may not be reflected in the C::P::A::User object - if this is required, re-authenticating
  61 ## the user is probably the best route to take.
  62 ## note that it is perfectly acceptable to return $self in cases where there is no underlying object.
  63 sub get_object {
  64     return shift;
  65 }
  66
  67 ## obj is shorthand for get_object.  This is originally from the DBIx::Class store, but
  68 ## as it has become common usage, this makes things more compatible.  Plus, it's shorter.
  69 sub obj {
  70     my $self = shift;
  71     return $self->get_object(@_);
  72 }
  73
  74 ## Backwards Compatibility
  75 ## you probably want auth_realm, in fact.  but this does work for backwards compatibility.
  76 ## store should be a read-write accessor - so it was moved to mk_accessors
  77 ##sub store {
  78 ##    my ($self) = @_;
  79 ##    return $self->auth_realm->{store};
  80 ##}
  81
  82 __PACKAGE__;
  83
  84 __END__
  85
  86 =pod
  87
  88 =head1 NAME
  89
  90 Catalyst::Authentication::User - Base class for user objects.
  91
  92 =head1 SYNOPSIS
  93
  94         package MyStore::User;
  95         use base qw/Catalyst::Authentication::User/;
  96
  97 =head1 DESCRIPTION
  98
  99 This is the base class for authenticated
 100
 101 =head1 METHODS
 102
 103 =head2 id( )
 104
 105 A unique ID by which a user can be retrieved from the store.
 106
 107 =head2 store( )
 108
 109 Should return a class name that can be used to refetch the user using it's
 110 ID.
 111
 112 =head2 supports( )
 113
 114 An introspection method used to determine what features a user object has, to support credential and authorization plugins.
 115
 116 =head2 get( $field )
 117
 118 Returns the value for the $field provided.
 119
 120 =head2 get_object( )
 121
 122 Returns the underlying object storing the user data.  The return value of this function will vary depending
 123 on the storage module used.
 124
 125 =head2 obj( )
 126
 127 Shorthand for get_object( )
 128
 129 =cut
 130