[4.x] Add HttpFactoryInterface and an aware interface and trait - #99

Summary of Changes

HttpFactory is a concrete class without an interface, so consumers (the CMS service provider from joomla/joomla-cms#47692, oauth2, github-api, …) cannot type against an abstraction or have a factory injected through an Aware interface.

This adds:

• Joomla\Http\HttpFactoryInterface with createHttp(array|\ArrayAccess $options = [], array|string|null $adapters = null): Http;
• Joomla\Http\HttpFactoryAwareInterface (setHttpFactory(?HttpFactoryInterface $httpFactory = null): void);
• Joomla\Http\HttpFactoryAwareTrait (the setter and a protected getHttpFactory() that throws UnexpectedValueException when no factory was set);
• HttpFactory implements HttpFactoryInterface, with a new createHttp() that delegates to getHttp(). getHttp() keeps its untyped signature, so subclasses are not affected.

Alternative to #80. The interfaces and the trait have the same API as there (createHttp(), so code written against #80 keeps working). The differences: HttpFactory actually implements the interface, which #80 leaves out (without that no instance of the interface exists in the package); the @since tags are __DEPLOY_VERSION__ (#80 has a broken docblock in HttpFactoryInterface, 4.1.0 on a line of its own); tests and docs are added. If you prefer to merge #80, the HttpFactory part, tests and docs of this PR can be applied on top of it instead.

As in #80 (and as in database, di and model for their aware traits), the trait gets a trait.unused entry in the PHPStan baseline, since nothing in src/ uses it.

Testing Instructions

Tests/HttpFactoryAwareTest.php (new): HttpFactory is an HttpFactoryInterface; createHttp() returns a client with the given options, and throws RuntimeException when no transport is available; the trait returns the factory that was set and throws UnexpectedValueException when none was.

Documentation Changes Required

docs/classes/HttpFactory.md: new section "Depending on the factory" on the interface, the aware interface and the trait.

🤖 Generated with Claude Code