Merge pull request #36 from aternosorg/align-constructor

⚠️ !Breaking Change! Reorder constructor parameters, remove $userAgent

Author: pavog

README.md

@@ -40,6 +40,8 @@ Most endpoints are public. Some endpoints (e.g. the daily stats of projects and
 require an API key, which you can create in your [account settings](https://hangar.papermc.io/auth/settings/api-keys).
 If an API key is set, it is used for all requests. The client exchanges it for a JWT automatically.
 ```php
+$hangarClient = new HangarAPIClient("your-api-key");
+// or
 $hangarClient->setApiKey("your-api-key");
 ```
 
@@ -67,13 +69,15 @@ try {
 
 ### Custom HTTP Client or Configuration
 You can pass your own [Guzzle](https://docs.guzzlephp.org/) client, e.g. to set timeouts or add middlewares,
-and your own `Aternos\HangarApi\Configuration`:
+and your own `Aternos\HangarApi\Configuration`.
+Each client creates its own configuration if none is passed, so changes to `Configuration::getDefaultConfiguration()`
+do not affect the client. A configuration passed to the client is used as is, so set your user agent on it.
 ```php
 use Aternos\HangarApi\Configuration;
 use GuzzleHttp\Client;
 
 $hangarClient = new HangarAPIClient(
-    configuration: new Configuration(),
+    configuration: new Configuration()->setUserAgent("my-app/1.0.0 (contact@example.com)"),
     httpClient: new Client(["timeout" => 10]),
 );
 // or

src/Client/HangarAPIClient.php

@@ -70,17 +70,22 @@ class HangarAPIClient
 
     protected PagesApi $pages;
 
+    /**
+     * @param string|null $apiKey API key used for authentication, see {@see setApiKey()}
+     * @param Configuration|null $configuration Configuration used for all requests. If null, a new configuration
+     * with the default user agent of this library is created, see {@see getDefaultUserAgent()}.
+     * @param ClientInterface|null $httpClient HTTP client used for all requests, see {@see setHttpClient()}
+     */
     public function __construct(
-        ?Configuration   $configuration = null,
         ?string          $apiKey = null,
+        ?Configuration   $configuration = null,
         ?ClientInterface $httpClient = null,
-        ?string          $userAgent = null,
     )
     {
         $this->apiKey = $apiKey;
         $this->httpClient = $httpClient;
         $this->setConfiguration($configuration ?? (new Configuration())
-            ->setUserAgent($userAgent ?? static::getDefaultUserAgent()));
+            ->setUserAgent(static::getDefaultUserAgent()));
     }
 
     /**

tests/Unit/Client/ClientTestCase.php

@@ -3,6 +3,7 @@
 namespace Aternos\HangarApi\Tests\Unit\Client;
 
 use Aternos\HangarApi\Client\HangarAPIClient;
+use Aternos\HangarApi\Configuration;
 use Aternos\HangarApi\Model\Pagination;
 use GuzzleHttp\Client;
 use GuzzleHttp\Handler\MockHandler;
@@ -35,14 +36,19 @@ public function setUp(): void
      * Create a client that answers every request with one of the given responses, in order,
      * and records all requests in {@see $requests}
      * @param Response[] $responses
-     * @param string|null $userAgent user agent passed to the constructor of the client
+     * @param string|null $apiKey API key passed to the constructor of the client
+     * @param Configuration|null $configuration configuration passed to the constructor of the client
      * @return HangarAPIClient
      */
-    protected function createClient(array $responses = [], ?string $userAgent = null): HangarAPIClient
+    protected function createClient(
+        array          $responses = [],
+        ?string        $apiKey = null,
+        ?Configuration $configuration = null,
+    ): HangarAPIClient
     {
         $stack = HandlerStack::create(new MockHandler($responses));
         $stack->push(Middleware::history($this->requests));
-        return new HangarAPIClient(httpClient: new Client(['handler' => $stack]), userAgent: $userAgent);
+        return new HangarAPIClient($apiKey, $configuration, new Client(['handler' => $stack]));
     }
 
     /**

tests/Unit/Client/HangarAPIClientTest.php

@@ -62,15 +62,37 @@ public function testDefaultUserAgentIsSentWithRequests(): void
     /**
      * @throws ApiException
      */
-    public function testUserAgentFromConstructorReplacesDefaultUserAgent(): void
+    public function testConfigurationFromConstructorIsUsed(): void
     {
-        $client = $this->createClient([new Response(200, [], "1.0.0")], "test-agent/1.0");
+        $configuration = new Configuration()
+            ->setHost("https://hangar.example.com")
+            ->setUserAgent("test-agent/1.0");
+        $client = $this->createClient([new Response(200, [], "1.0.0")], configuration: $configuration);
 
         $client->getLatestReleaseVersion("mclogs");
 
+        $this->assertEquals("hangar.example.com", $this->getRequest()->getUri()->getHost());
         $this->assertEquals("test-agent/1.0", $this->getRequest()->getHeaderLine("User-Agent"));
     }
 
+    /**
+     * @throws ApiException
+     */
+    public function testApiKeyFromConstructorIsUsedForAuthentication(): void
+    {
+        $client = $this->createClient([
+            new Response(200, [], json_encode(["token" => "test-jwt", "expiresIn" => 3600])),
+            new Response(200, [], "1.0.0"),
+        ], "test-api-key");
+
+        $client->getLatestReleaseVersion("mclogs");
+
+        $this->assertEquals("POST", $this->getRequest(0)->getMethod());
+        $this->assertEquals("/api/v1/authenticate", $this->getRequest(0)->getUri()->getPath());
+        $this->assertEquals(["apiKey" => "test-api-key"], $this->getQuery(0));
+        $this->assertEquals("Bearer test-jwt", $this->getRequest(1)->getHeaderLine("Authorization"));
+    }
+
     /**
      * @throws ApiException
      */