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