Reason

[Swader]

Todo: implement reasons.

I.e. when authorize() returns false, the user should be able to call $rauth->getReason() or something and get coherent feedback about why an authorization attempt failed. This needs to take into account bans, mismatches due to mode, and anything else additionally implemented. So biggest problem is finding a good reason format.

[AndrewCarterUK]

Could authorize() throw an authorization exception on failure, with the reason being the exception message? You could even have different exceptions for different reasons.

[Swader]

It could but:

• an exception thrown at first failure is more performant, but might skip over some additional reasons (i.e. in AND mode, the user needs to have ALL the groups - the verification could fail after the very first check - do we throw then already, or do we scan fully, and throw for all?)
• I'm not keep on reasons being exception messages because I want to allow people to construct their own messages in their own language. As such, I would rather return an array with keys like reason, type, has, needs and similar, but that quickly becomes chaotic. Perhaps a custom extension class with those properties?

[AndrewCarterUK]

I guess there is a use case for knowing all of the reasons that an auth failed. Maybe you need a Reason object and an auth exception could return an array containing at least one.

[Swader]

Hmm. That's two new objects and complicates the main class by quite a lot, due to having to create the reasons when they occur and push them into the exception to be thrown. It would be a clean solution, but I'm afraid of potential overkill.

[Swader]

This is what I'm currently thinking:

• each mode is its own context and checks the authorization
• if invalid, throws AuthException and sets a mode on the exception, matching the mode
• each exception also contains an array of Reason objects. Each Reason object has the following properties: type (ban or mismatch), group (which @auth-tag triggered it), has for the attributes present in that group and needs for the attributes needed (or disallowed if group is NONE) in that group. A reason doesn't have the mode.

My current concern is that AuthException would then have the mode set on itself, but the reasons would be mode-less. That's two objects saying a part of the whole "what went wrong message". This lends itself nicely to #6 because third party modes can throw their own exceptions / modes then and Reasons aren't coupled to modes, but feels wrong.

[Swader]

Alternative is adding another property into Reason: $mode. However, this seems superfluous given that a set of reasons will all have the same mode if in the same exception.

Also considered having a separate exception for each mode (NoneException, AndException, etc) but this would quickly get out of hand, especially when trying to build the catch blocks, unless one builds a single catch block that catches the parent AuthException, in which case it's the same as if we just add $mode into AuthException and grab that - no need for extra classes.

[Swader]

Rubberducking further, perhaps $errorType should be removed from Reason altogether, and the AuthException should get a $type property which can be set to: ban, and, or, or none. This gives sufficient context to the exception and all reasons inside it, and the reason objects still contain the group, has, and needs, identifying the exact problem areas.

[Swader]

Closed via #8 but still up for improvement. Make a new issue / PR for any additional tweaks.