Merge JakobBruening/username-authentication

docs/Authorization.md

@@ -1,9 +1,14 @@
 # Authorization
 
-**API reference**: https://api.immobilienscout24.de/api-docs/import-export/attachment/overview/
+**API reference**: https://api.immobilienscout24.de/api-docs/authentication/three-legged/
 <br><br>
 
 To access the api, you have to be registered on https://api.immobilienscout24.de.
+<br>
+You can then request a permanent token using Consumer Key & Secret to authenticate your account. An example of how to
+get this token can be found here: https://api.immobilienscout24.de/api-docs/postman/postman-collections/. This package
+only supports authentication via three-legged oAuth, as authentication via three-legged oAuth is required for user
+endpoints.
 
 There are two ways bringing your auth keys into the code!
 
@@ -18,7 +23,7 @@ IMSC_TOKEN_SECRET=YOUR_TOKEN_SECRET
 
 2. Add it to your code
 
-````php
+```php
 // set auth data
 $authData = [
     'consumer_key'      => 'YOUR_CONSUMER_KEY',
@@ -31,7 +36,33 @@ $authData = [
 $realEstate = new RealEstate($authData);
 $contact = new Contact($authData);
 ...
-````
+```
 
 You can find all information about the authentication system in
-the [ImmoScout24 API documentation](https://api.immobilienscout24.de/api-docs/authentication/introduction/).
+the [ImmoScout24 API documentation](https://api.immobilienscout24.de/api-docs/authentication/introduction/).
+
+<hr>
+
+### Change the user
+
+You can also pass a custom user. 
+The username must be he username which the user uses for logging in to www.immobilienscout24.
+You can configure the user either via .env-file
+
+```dotenv
+IMSC_USERNAME=yourusername
+```
+
+or by passing it to the class constructor
+
+```php
+// with auth data
+$realEstate = new RealEstate($authData, 'yourusername');
+
+// without auth data
+$contact = new RealEstate(null, 'yourusername');
+```
+
+Per default, the username is set to "me" (the profile that created the auth data).
+<br>
+**Important**: Keep in mind, that additional users must be authenticated via oAuth!

src/Immoscout/ApiRequest.php

@@ -20,11 +20,14 @@ class ApiRequest
 {
     private Client $client;
 
-    protected const API_URL = 'https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/me/%s';
+    private string $user;
 
-    public function __construct(?array $auth = null)
+    protected const API_URL = 'https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/%s/%s';
+
+    public function __construct(?array $auth = null, ?string $user = null)
     {
         $this->client = $this->getPreparedClient($auth);
+        $this->user = $user ?? $_ENV['IMSC_USERNAME'] ?? 'me';
     }
 
     /**
@@ -63,7 +66,7 @@ private function getPreparedClient(?array $authData = null): Client
     protected function request(string $url, string $method = 'GET'): array
     {
         try {
-            $request = $this->client->request($method, sprintf(self::API_URL, $url));
+            $request = $this->client->request($method, sprintf(self::API_URL, $this->user, $url));
         } catch (GuzzleException $e) {
             throw new ApiException($e->getMessage(), $e->getCode());
         }
@@ -76,4 +79,4 @@ protected function request(string $url, string $method = 'GET'): array
 
         return $data;
     }
-}
+}