[fix_SSH2_class] Introduce a fix for inconsistent return type problem."

[func0der]

Proposed fix for #1471

I just started replacing all return false with exceptions. This is just a proposition. Before I migrate the whole class, I would like some input on this :)

There might be some problems with other classes, since there were private classes used outside of the scope of the class SSH2 (for example in SCP), but they might be resolvable by simply introducing real public methods that wrap the private ones, catch the new exceptions and return the old (read: wrong) return types.

[terrafrost]

Throwing exceptions in the 2.0 branch is a non starter as it's a BC break. The 3.0 branch, however, does throw exceptions.

As for the issue that this is attempting to fix... I'll take a look in the next few days as time permits!

Thanks!

[func0der]

Throwing exceptions in the 2.0 branch is a non starter as it's a BC break.

The only changes made are those to "private" methods (those with an _ (underscore) in front of it). If someone was to use those methods, they would use the library wrong.
Also the @access PHPDoc states that those methods are private.

It would be possible to have the internal code throw exceptions and the external api to keep returning the falsely documented results like "false" etc.

[terrafrost]

It would be possible to have the internal code throw exceptions and the external api to keep returning the falsely documented results like "false" etc.

The public functions would need to catch the exceptions thrown by the private exceptions and return false, if appropriate, instead. At least for the code changes not to be BC breaking.

Like consider this example:

function a()
{
    throw new \Exception('demo');
}

function b()
{
    a();
}

b();

The exception a() throws will kinda float up to b().

And make no mistake the changes are BC breaking. Exceptions do offer a lot of advantages over doing user_error() but user_error() won't kill a program whereas an uncaught exception will.

Also, I'd do one or the other (user_error() or throwing an exception) - not both.

Finally, I'm not the biggest fan of including the full SSH packet in the exceptions. The full SSH packet is going to be binary encoded and ran over a command line it could mess up how stuff displays. As a simple demonstration...

for ($i = 128; $i <= 255; $i++) {
    echo chr($i);
}

Does that actually output anything for you? It doesn't output anything for me.