view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/Authentication/Internals.pod  view on Meta::CPAN

care to avoid overlapping element names.

Please note that this routine may be called numerous times in various
circumstances, and that a successful match for a user here does B<NOT>
necessarily constitute successful authentication. Your store class should
never assume this and in most cases C<$c> B<should not be modified> by your
store object.

=item for_session( $c, $user )

This method is responsible for preparing a user object for storage in the session.
It should return information that can be placed in the session and later used to
restore a user object (using the C<from_session()> method).  It should therefore
ensure that whatever information provided can be used by the C<from_session()>
method to locate the unique user being saved.  Note that there is no guarantee
that the same Catalyst instance will receive both the C<for_session()> and
C<from_session()> calls.  You should take care to provide information that can
be used to restore a user, regardless of the current state of the application.
A good rule of thumb is that if C<from_session()> can revive the user with the
given information even if the Catalyst application has just started up, you are
in good shape.

=item from_session( $c, $frozenuser )

This method is called whenever a user is being restored from the session.
C<$frozenuser> contains the information that was stored in the session for the user.
This will under normal circumstances be the exact data your store returned from
the previous call to C<for_session()>.  C<from_session()> should return a valid
user object.

=item user_supports( $feature, ...  )

This method allows credentials and other objects to inquire as to what the
underlying user object is capable of. This is pretty-well free-form and the
main purpose is to allow graceful integration with credentials and
applications that may provide advanced functionality based on whether the
underlying user object can do certain things. In most cases you will want to
pass this directly to the underlying user class' C<supports> method. Note that
this is used as a B<class> method against the user class and therefore must
be able to function without an instantiated user object.

=back

=head3 OPTIONAL STORE METHODS

If you want your store to be able to auto- create users, then you can
implement these methods:

=head4 auto_update_user( $authinfo, $c, $res )

This method is called if the realm's auto_update_user setting is true.

=head4 auto_create_user( $authinfo, $c )

This method is called if the realm's auto_create_user setting is true.

=head2 USER OBJECT

The user object is an important piece of your store module. It will be the
part of the system that the application developer will interact with most. As
such, the API for the user object is very rigid. All user objects B<MUST>
inherit from
L<Catalyst::Authentication::User|Catalyst::Authentication::User>.

=head3 USER METHODS

The routines required by the
L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> plugin
are below. Note that of these, only get_object is strictly required, as the
L<Catalyst::Authentication::User|Catalyst::Authentication::User>
base class contains reasonable implementations of the rest. If you do choose
to implement only the C<get_object()> routine, please read the base class code
and documentation so that you fully understand how the other routines will be
implemented for you.

Also, your user object can implement whatever additional methods you require
to provide the functionality you need. So long as the below are implemented,
and you don't overlap the base class' methods with incompatible routines, you
should experience no problems.

=over 4

=item id( )

The C<id()> method should return a unique id (scalar) that can be used to
retreive this user from the store.  Often this will be provided to the store's
C<find_user()> routine as C<id =E<gt> $user-E<gt>id> so you should ensure that your
store's C<find_user()> can cope with that.

=item supports( $feature, $subfeature ... )

This method checks to see if the user class supports a particular feature.  It
is implemented such that each argument provides a subfeature of the previous
argument. In other words, passing 'foo', 'bar'  would return true if the user
supported the 'foo' feature, and the 'bar' feature of 'foo'.   This is implemented
in Catalyst::Authentication::User, so if your class inherits from that, you
do not need to implement this and can instead implement supported_features().

B<Note:> If you want the authentication module to be able to save your user in
the session you must return true when presented with the feature 'session'.

=item supported_features( )

This method should return a hashref of features supported by the user class.
This is for more flexible integration with some Credentials / applications. It
is not required that you support anything, and returning C<undef> is perfectly
acceptable and in most cases what you will do.

=item get( $fieldname )

This method should return the value of the field matching fieldname provided,
or undef if there is no field matching that fieldname. In most cases this will
access the underlying storage mechanism for the user data and return the
information. This is used as a standard method of accessing an authenticated
user's data, and MUST be implemented by all user objects.

B<Note>: There is no equivalent 'set' method. Each user class is
likely to vary greatly in how data must be saved and it is
therefore impractical to try to provide a standard way of
accomplishing it. When an application developer needs to save
data, they should obtain the underlying object / data by