search

web-token / jwt-doc

Documentation for the JWT Framework
MIT License
12 stars 19 forks source link

Instantiating AlgorithmManager #11

Closed ingalless closed 5 years ago

ingalless commented 5 years ago

On this page of the docs an example is given of creating a Jose\Component\Core\AlgorithmManager, like the below

$algorithm_manager = new AlgorithmManager([ new PS256(), new ES512(), ]);

However, the constructor function for Jose\Component\Core\AlgorithmManager is private. Shouldn't this use the public static "create" method, like below? $algorithm_manager = AlgorithmManager::create([ new PS256(), new ES512(), ])

Hope that makes sense, let me know if you need any more info!

Spomky commented 5 years ago

Hi @ingalless,

I recently updated the documentation. This syntax will correspond to the v2.0 to come. The one with the create method is the valid way for v1.x and will be marked as obsolete soon.

I have to find a way to manage the doc versions a better way. It is difficult to differentiate the feature / proper method in the current configuration.

Spomky commented 5 years ago

I’ve created new branches of the documentation. Should be ok now. Feel free to open this issue again if not.

ingalless commented 5 years ago

@Spomky Looks perfect! Glad it's helped someone else out too.

Thanks for this library, it's great! 👍

Spomky commented 5 years ago

You’re welcome! I think it is relevant to create a branch for all minor versions i.e. v1.0, 1.1… and avoid messages like This feature was introduced in version 1.x.

ingalless commented 5 years ago

That seems a good idea! Although mentioning something like new to 1.x is... in the docs could be a nice addition for developers unaware of new features? An example from this page below

New to version 1.1, If you already have a shared secret, you can use it to create an oct key

The English there isn't great, but I hope it conveys the idea.

It might be a good idea to include an upgrade guide for major releases too? (Example) If anything, it will save me some confusion when I upgrade to 2.x in future and have the inverse of the issue I've just faced 😆

Spomky commented 5 years ago

Ok I will try to improve that way. Normally the upgrade from v1.x to v2.0 will be smooth. The idea is to mark methods/classes/… as deprecated in v1.x with a message for replacement. When you have no deprecation message, then you will be able to upgrade without any change but the package versions.