Wrong documentation in the readme

[stof]

the documentation link in the readme points to http://phpseclib.sourceforge.net/ which describes a PHP4+ library with class names like Net_SFTP. this does not match the codebase at all. Please update the documentation to actually document the library.

[GrahamCampbell]

It matches 1.0.0, which is the current LTS release.

[stof]

well, then it should not be the link in the master branch. the readme of the master branch should point to its own documentation.

and on a side note, having a changelog for 2.0 would be good

[GrahamCampbell]

The master branch isn't due for release for at least a year.

[GrahamCampbell]

It doesn't have any docs yet, and is still changing a lot.

[GrahamCampbell]

Also, there is a change log of sorts: https://github.com/phpseclib/phpseclib/wiki/Roadmap.

[stof]

Well, 2.0 is tagged, and it does not have documentation or changelog either (a roadmap is not the same than a changelog for existing release)

[cryptiklemur]

If the documentation doesn't match the master branch code, it shouldn't be the linked documentation. At the very least, master should label the link "1.0.0 documentation" and have a link to another set for master/2.0.0

[GrahamCampbell]

I don't agree anything needs changing, however, I would suggest making the 1.0 or 2.0 the "default" branch on GitHub rather than the master, like symfony and laravel do, so it's not confusing for people.

[cryptiklemur]

Why would you not have the master branch have its documentation? I agree about changing the default branch though.

[GrahamCampbell]

The master branch has no docs, because the code there is unfinished for at least a year.

[cryptiklemur]

So then remove the doc link

[terrafrost]

The master branch will presumably always be unfinished. By the time the API in the master branch is finalized it'd be 3.0 or 4.0 or whatever.

As for the 2.0 branch... the API is essentially the same. The only difference being that in 2.0 it's namespace'd and you have to use an autoloader. It's available for people wanting to people wanting to avoid deprecated warnings from the 1.0 branch's using PHP4 style constructors and who want to avoid class conflicts vis-a-vis namespaces.

The documentation isn't quite up-to-date but it's mostly still relevant.

For that matter the documentation for 1.0 is in need of updates. A lot of new additions aren't documented in it. But there's also the fact that it just isn't a high priority for me. When 3.0.0 is released (or maybe before it's released, concurrent to 3.0.0's release) I plan on pretty much redoing the documentation.

In the mean time, if people want to see improvements they are free to submit pull requests or whatever.

[mAAdhaTTah]

FWIW, composer require phpseclib/phpseclib pulls in version ^2.0 at this point, so if you're working with it that way, you're getting 2.0. The documentation hasn't been an issue just yet, but maybe a data point worth considering.

[GrahamCampbell]

1.0 is the LTS release though. Not our fault if composer doesn't have a concept of LTS.

[cryptiklemur]

Symfony has LTS, and yet Symfony also doesn't have a problem with its documentation.

[GrahamCampbell]

Yeh, but they have people that contribute to the docs. I'm sure the phpseclib team would be happy if you could help write some docs.

[cryptiklemur]

An easier solution would be to follow some of the earlier suggestions.

[mAAdhaTTah]

Should we be treating 2.0 as more of a beta/incomplete? Or is that a stable version? If it's stable and wanted to contribute to the docs, where should we pull against?

[terrafrost]

2.0 is stable.

To contribute to the docs make a pull request against https://github.com/phpseclib/docs and post here as I don't check the issues / PR's there very often.

If you want to completely redo the documentation, too, feel free. But for a redo it'd prob be best to do so in your own repo for the time being until it's been vetted. If it looks good maybe it can become an official phpseclib sub project.

[bantu]

Obviously we could use some help with the documentation. I am happy to assist setting a new system up, should that be necessary. We can also make use of the phpseclib.org domain now.

[philBrown]

Please just remove the link. The 2.0.x tagged versions still point to the SourceForge docs

[terrafrost]

That's not going to happen. Documentation that's 90% accurate is still better than no documentation at all imho. At best maybe I can create a "splash" page for 2.0 that discusses the differences and then links to the 1.0 documentation.

The closest thing that exists currently is this blurb at the bottom of http://phpseclib.sourceforge.net/ :

Other Branches: 2.0 and master

The 2.0 branch has pretty much the exact same API as the 1.0 branch, save for that it is namespaced, uses PHP5-style constructors (thereby avoiding E_DEPRECATED errors) and requires the use of an autoloader. A few examples.

The master branch has an unstable API that is subject to change. The master branch will eventually turn into 3.0, at which point, this website will be re-designed with an emphasis on that version.

I could expand on that in a splash page that you get taken to when you click on the documentation link for 2.0 in README.md.

Of course, I'm also not going to do that asap either. Maybe this weekend or next weekend. Higher priority than that: providing support for outstanding support requests.

[terrafrost]

I assume you're the Phil from https://stackoverflow.com/questions/47684852/upload-csv-file-to-server-using-sftp . The the fact that the constant is different also came up in another very recent stackoverflow question:

https://stackoverflow.com/questions/47659231/phpseclib-sftp-put-command-file-contents-are-just-a-string-not-the-expected

So that's a known issue and will be addressed in the fullness of time.

So to summarize, the only real differences between 1.0 and 2.0 are...

• Use of namespaces, which has brought about the renaming of some classes (eg. Net_SFTP to phpseclib\Net\SFTP)
• The use of an autoloader is required
• Some constants have been renamed (eg. NET_SFTP_LOCAL_FILE to SFTP::SOURCE_LOCAL_FILE)

Beyond that the API is largely identical. The method names are all the same, the parameters all do the same stuff, etc.

If you find other instances where there are differences I'd (1) be surprised and (2) would appreciate elucidation.

[terrafrost]

@philBrown - I've updated the documentation as it currently exists to present users with a modal dialog box asking for the version they're using when viewing the examples. You'll be directed to the appropriate example based on that and a cookie will then be set as well so that on subsequent visits you'll see the documentation for that version.