Improve Builder interface methods

[lcobucci]

As per @henriquemoody and @Ocramius reviews on #129 we can make things more clear.
So let's discuss here to find the best names for with(), canOnlyBeUsedBy() and other method we would like to discuss about.

[lcobucci]

withClaim() is clearly better than with()

[lcobucci]

@Ocramius would allowedTo() be better than canOnlyBeUsedBy()? I think is pretty logical and also compatible with the constraints we created.

[Ocramius]

allowedTo... do what? (that's the question I ask myself when reading allowedTo.

[lcobucci]

allowed to as in "allowed to client A"

[Ocramius]

Still lacks expressiveness...

[lcobucci]

😭

[Ocramius]

@lcobucci ask the twitters?

[lcobucci]

@Ocramius can you do it plz?

[rdohms]

clearedFor as in "security clearance for client a"

[rdohms]

or restrictedTo if the only is still relevant.

[greg0ire]

grantedTo, like a right? I like restrictedTo too.

[nikolaposa]

I find allow more appropriate as a term than restrict because with every subsequent invocation of a method you are widening scope instead of narrowing it.

[nikolaposa]

... that being said, here are my suggestions:

• allow()
• validFor()
• permit()
• permittedFor()
• grant()

[rdohms]

@nikolaposa but the original name canOnlyBeUsedBy implies that its replacing all other grants with one restricted to the passed user. That's why i asked if the only is relevant.

[nikolaposa]

@rdohms Concrete implementation tells me that the actual idea of how method should behave is different: https://github.com/lcobucci/jwt/blob/master/src/Token/Builder.php#L63

[rdohms]

that's just bad naming then, i blame @lcobucci :D

[lcobucci]

that's just bad naming then, i blame @lcobucci :D

@rdohms that's why this issue exists (so that people can come and blame me ofc 😄)

[lcobucci]

Thanks for the suggestions guys!

The idea of the aud claim is to have a list of clients that are allowed to use the token (basically a whitelist).

I'd say that permittedFor() is the closest one for that concept but I'm not sure it expresses what we want. Maybe dropping canBeUsedBy() is also a good idea (since it's causing the whole confusion), what you think @Ocramius?

[Ocramius]

@lcobucci "permission" is probably the closest to what the claim expresses (thanks for nothing, abbreviations, DUH.).

I'd go with permittedFor

[lcobucci]

@Ocramius cool let's go with that then. Do you think we should rename Lcobucci\JWT\Validation\Constraint\AllowedTo to make it consistent?