Clearer exception messages.

[Nyholm]

Q	A
Bug fix?	yes
New feature?	yes
BC breaks?	no
Deprecations?	yes
Related tickets	na
Documentation	php-http/documentation#165
License	MIT

Relates to mailgun/mailgun-php#222

If discovery fails we get an error like:

Fatal error: Uncaught Http\Discovery\Exception\PuliUnavailableException: Puli Factory is not available in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/MessageFactoryDiscovery.php on line 27

Http\Discovery\NotFoundException: No message factories found. To use Guzzle, Diactoros or Slim Framework factories install php-http/message and the chosen message implementation. in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/MessageFactoryDiscovery.php on line 27

Call Stack:
    0.0006     353240   1. {main}() /Users/tobias/Workspace/PHPStorm/test/index.php:0
    0.0023     506296   2. Mailgun\Mailgun->get() /Users/tobias/Workspace/PHPStorm/test/index.php:6
    0.0023     506352   3. Mailgun\Connection\RestClient->get() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Mailgun.php:129
    0.0024     506384   4. Mailgun\Connection\RestClient->send() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:167

Which leads users to think ""wtf is Puli?"..

---

With this PR we get an exception like this instead. This is more descriptive:

Fatal error: Uncaught Http\Discovery\Exception\DiscoveryFailedException: Could not find resource using any discovery strategy. Find more information at http://docs.php-http.org/en/latest/discovery.html#common-errors
 - Puli Factory is not available

 in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/MessageFactoryDiscovery.php on line 27

Http\Discovery\NotFoundException: No message factories found. To use Guzzle, Diactoros or Slim Framework factories install php-http/message and the chosen message implementation. in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/MessageFactoryDiscovery.php on line 27

Call Stack:
    0.0005     353240   1. {main}() /Users/tobias/Workspace/PHPStorm/test/index.php:0
    0.0023     506296   2. Mailgun\Mailgun->get() /Users/tobias/Workspace/PHPStorm/test/index.php:6
    0.0023     506352   3. Mailgun\Connection\RestClient->get() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Mailgun.php:129
    0.0023     506384   4. Mailgun\Connection\RestClient->send() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:167
    0.0028     531816   5. Http\Discovery\MessageFactoryDiscovery::find() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:96

When php-http/message and a PSR7 is installed and I try to rerun I get an exception like:

Fatal error: Uncaught Http\Discovery\Exception\DiscoveryFailedException: Could not find resource using any discovery strategy. Find more information at http://docs.php-http.org/en/latest/discovery.html#common-errors
 - Puli Factory is not available

 in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/HttpClientDiscovery.php on line 27

Http\Discovery\NotFoundException: No HTTPlug clients found. Make sure to install a package providing "php-http/client-implementation". Example: "php-http/guzzle6-adapter". in /Users/tobias/Workspace/PHPStorm/test/vendor/php-http/discovery/src/HttpClientDiscovery.php on line 27

Call Stack:
    0.0007     353240   1. {main}() /Users/tobias/Workspace/PHPStorm/test/index.php:0
    0.0031     631456   2. Mailgun\Mailgun->get() /Users/tobias/Workspace/PHPStorm/test/index.php:6
    0.0031     631512   3. Mailgun\Connection\RestClient->get() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Mailgun.php:129
    0.0031     631544   4. Mailgun\Connection\RestClient->send() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:167
    0.0070     907896   5. Mailgun\Connection\RestClient->getHttpClient() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:97
    0.0072     911024   6. Http\Discovery\HttpClientDiscovery::find() /Users/tobias/Workspace/PHPStorm/test/vendor/mailgun/mailgun-php/src/Mailgun/Connection/RestClient.php:291

[Nyholm]

Im done with this PR.
I also added more documentation about this: php-http/documentation#165

[dbu]

👍

[dbu]

this is eating away the chance to see a root cause exception. in general, it could be useful to see where the original problem comes from. but in the situation i agree it would be more confusing than helpful.

[Nyholm]

I've been back and forth with this. But I believe this is the best solution.

Say that you have 5 different strategies. 4 of them fails (StrategyUnavailable), The exception message for the first exception will say "Puli factory not found". But your intention was to use "FoobarStrategy". So "Puli" will be confusing.

The new message will be:

Fatal error: Uncaught Http\Discovery\Exception\DiscoveryFailedException: Could not find resource using any discovery strategy. Find more information at http://docs.php-http.org/en/latest/discovery.html#common-errors
 - Puli Factory is not available
 - Foobar strategy is not available
 - Something else. 

[dbu]

i agree with you. just wanted to point this out so we are aware of it.

[Nyholm]

I added a change log

[sagikazarmark]

Looks good to me