lib/Catalyst/Authentication/User.pm

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