[Catalyst] Some bits missing/wrong in the docs for the dev version of C::P::Authentication

[Jay K]

Hi Dave,

Thanks for the feedback.  You are definitely right about the
session / supports issue, I'll add some wording to make that clear.

Regarding supported_features, supports, and user_supports, you are
partially correct and it is definitely confusing.  Let me try to shed
some light.

First, $user->supports and $storagebackend->user_supports are the
official interfaces for the application developer.   $user->supports
is obviously the correct call to make if you have a user object  to
work with.  There are situations, such as when working within a
credential, store, or other internal auth module, however, when you
may not have a user yet.   You may still want to know what features
the user will support.  This is where the $store->user_supports comes
in - as it allows you to check what features the user class will have.

$user->supports is a class method - but it is possible that the same
store could return multiple different classes representing a user -
so having the storage module handle this is the only course that
really makes sense.  In many cases $store->user_supports will just
call the user class supports method anyway - but there is no rule
that says this must be the case for every storage module.

Finally - supported_features.  Catalyst::Plugin::Authentication::User
implements supports() - and calls supported_features to retrieve a
hashref of features supported by the user object, and then supports()
does the necessary work to compare this hashref to the features
passed to supports();   In other words, the base user class lets you
be lazy in your user class by simply implementing
supported_features.  There is no rule that says you can't implement
'supports' yourself in your user class, though.

Does this all make sense to you?

Thanks again for the feedback.  I know this is all a little confusing
and I will work on explaining this better in the docs.

JayK

On Mar 4, 2007, at 10:34 AM, Dave Rolsky wrote:

> I was trying to figure out why the authen/session integration bits
> weren't working and I realized there's a couple problems in the
> docs here.
>
> First, AFAICT, there's no mention that beyond setting "use_session"
> to true in your config, you have to indicate that your user class
> supports sessions.
>
> Second, the method documentation in C::P::A::Internals suggests
> that you should provide a method named "supports_features" in your
> user class. However, looking at the code, it seems like this method
> is expected to be named "support".
>
> Finally, those same internals docs mention a Store class method
> "user_supports", which AFAICT is kind of redundant, and not really
> used anyway.
>
>
> -dave
>
> /*===================================================
> VegGuide.Org                        www.BookIRead.com
> Your guide to all that's veg.       My book blog
> ===================================================*/
>
> _______________________________________________
> List: Catalyst at lists.rawmode.org
> Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
> Searchable archive: http://www.mail-archive.com/
> catalyst at lists.rawmode.org/
> Dev site: http://dev.catalyst.perl.org/

---
America will never be destroyed from the outside. If we falter and
lose our freedoms, it will be because we destroyed ourselves. --
Abraham Lincoln