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
  76 __PACKAGE__->meta->make_immutable;
  77 __PACKAGE__;
  78
  79 __END__
  80
  81 =pod
  82
  83 =head1 NAME
  84
  85 Catalyst::Authentication::User - Base class for user objects.
  86
  87 =head1 SYNOPSIS
  88
  89         package MyStore::User;
  90         use base qw/Catalyst::Authentication::User/;
  91
  92 =head1 DESCRIPTION
  93
  94 This is the base class for authentication user objects.
  95
  96 THIS IS NOT A COMPLETE CLASS! it is intended to provide base functionality only.
  97
  98 It provides the base methods listed below, and any additional methods
  99 are proxied onto the user object fetched from the underlieing store.
 100
 101 =head1 NOTES TO STORE IMPLEMENTORS
 102
 103 Please read the comments in the source code of this class to work out
 104 which methods you should override.
 105
 106 =head1 METHODS
 107
 108 =head2 id( )
 109
 110 A unique ID by which a user can be retrieved from the store.
 111
 112 =head2 store( )
 113
 114 Should return a class name that can be used to refetch the user using it's
 115 ID.
 116
 117 =head2 supports( )
 118
 119 An introspection method used to determine what features a user object has, to support credential and authorization plugins.
 120
 121 =head2 get( $field )
 122
 123 Returns the value for the $field provided.
 124
 125 =head2 get_object( )
 126
 127 Returns the underlying object storing the user data.  The return value of this
 128 method will vary depending
 129 on the storage module used.
 130
 131 =head2 obj( )
 132
 133 Shorthand for get_object( )
 134
 135 =head2 AUTOLOAD
 136
 137 Delegates any unknown methods onto the user object returned by ->obj
 138
 139 =cut
 140