search

lcobucci / jwt

A simple library to work with JSON Web Token and JSON Web Signature
https://lcobucci-jwt.readthedocs.io/en/stable/
BSD 3-Clause "New" or "Revised" License
7.31k stars 601 forks source link

update documentation to require specific version of lcobucci/jwt? #1068

Closed prescriptionlifeline closed 4 months ago

prescriptionlifeline commented 4 months ago

I installed lcobucci/jwt by doing composer require lcobucci/jwt as suggested at https://lcobucci-jwt.readthedocs.io/en/stable/installation/#autoloading . I then tried to run the code for issuing tokens at https://lcobucci-jwt.readthedocs.io/en/stable/quick-start/#issuing-tokens and then got this error:

Fatal error: Uncaught Error: Class "Lcobucci\JWT\JwtFacade" not found

Turns out composer require lcobucci/jwt installed 4.0.4. When I did composer require lcobucci/jwt:~5.3.0 I got this error:

  Problem 1
    - Root composer.json requires lcobucci/jwt ~5.3.0 -> satisfiable by lcobucci/jwt[5.3.0].
    - lcobucci/jwt 5.3.0 requires ext-sodium * -> it is missing from your system. Install or enable PHP's sodium extension.

Upon seeing that I added ext-sodium to my system and the problem went away, but still, this issue would have been a lot easier to diagnose if the documentation did composer require lcobucci/jwt:~5.3.0 instead of composer require lcobucci/jwt

SvenRtbg commented 4 months ago

For anyone who simply wants to use this library in any version that is compatible with the system they own, the opposite would be true - requiring a specific version that cannot be installed due to dependencies missing may be a true obstacle.

This boils down to: "What level of experience with using Composer as a tool the documentation should rely on?" What level of research can be expected? Would a user know there are more versions available, and which version to expect getting installed? Is it common knowledge that composer require vendor/package allows specifying a version range? Or does the install doc need to hold everyones hand regardless of their knowledge level with the tool?

If the answer is "yes", then the docs need to be updated at least with every major version released (as I would suggest using ^5.0 as the version, and if really tight ranges are required, ^5.3.0, not ~5.3.0).

Ocramius commented 4 months ago

TBH, I'd expect composer require <package> to pick ^current-stable by default, but this should be brought up with composer/composer.

Requiring the package itself to adjust its README.md at every release is not helpful / ain't gonna happen anyway :-)

Closing here: please raise it as a question in https://github.com/composer/composer