lib/Catalyst/Plugin/Authentication/User.pm

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