Verwendung

1. Bibliothek in composer.json einbinden

{
    "require": {
        "locr/user-client": "^1.0"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://x-token-auth:<secret-auth-token>@bitbucket.org/locr/php-user-client.git"
        }
    ]
}

2. Composer mit neu hinzugefügter Bibliothek aktualisieren

$ composer update

3. Beispiele für die Verwendung der Bibliothek im Code

3.1. Authentifizierung, Login und Logout

3.1.1. Authentifizierung eines Benutzers. Erstellen und speichern eines User-Tokens auf dem Server, sowie setzen eines Cookies für nachfolgende Aufrufe (Login)

<?php

use Locr\Lib\UserClient\Services\{Config, UserService, UserTokenService};

$config = Config::factory();
$userService = new UserService(config: $config);

// Der folgende Aufruf wirft eine Exception, wenn die Authentifizierung fehlschlägt
$user = $userService->authenticateByUsernamePassword('<username>', '<secret-password>');
// Alternativ kann auch die Authentifizierung über den API-Key erfolgen
$user = $userService->authenticateByApiKey('<uuid>');

$userTokenService = new UserTokenService($config);
$userTokenService->setCookie($userTokenService->createToken($user));

3.1.2. Per Cookie eingeloggten Benutzer verifizieren und User-Objekt holen

<?php

use Locr\Lib\UserClient\Services\{Config, UserTokenService};

$userTokenService = new UserTokenService(config: Config::factory());
$user = $userTokenService->readTokenByCookie()?->getUser();

3.1.3. Berechtigungen eines Benutzers prüfen

<?php

if ($user->Role === 'admininistrator') {
    // Benutzer hat Admin-Rechte
}
if ($user->hasAuthorization('app-1')) {
    // Benutzer hat Zugriff auf App 1
}

3.1.4. Abmelden eines Benutzers (Logout)

<?php

use Locr\Lib\UserClient\Services\{Config, UserTokenService};

$userTokenService = new UserTokenService(config: Config::factory());
$userTokenService->deleteTokenByCookie();

3.1.5. ungültige und abgelaufene Tokens löschen

<?php

use Locr\Lib\UserClient\Services\{Config, UserTokenService};

$userTokenService = new UserTokenService(config: Config::factory());
$userTokenService->cleanupInvalidTokens()->cleanupExpiredTokens();

3.2. Api-Key Nutzung

3.2.1. Api-Key prüfen

<?php

use Locr\Lib\UserClient\Services\{Config, ApiKeyService};
use Locr\Lib\UserClient\ValueObjects\ApiKey\Value;

$apiKeyService = new ApiKeyService(config: Config::factory());
// Die folgenden Aufrufe können eine Exception werfen, wenn die API-Schlüssel ungültig sind.
$apiKey = $apiKeyService->verifyAndReceiveApiKeyData(apiKeyValue: new Value('<api-key>'));
$apiKey->checkExpirationDateClaim();

3.3. AccessLog

3.3.1. Eintrag erstellen

<?php

use Locr\Lib\UserClient\Services\{Config, AccessLogService};
use Locr\Lib\UserClient\ValueObjects\{Origin, UserId};
use Locr\Lib\UserClient\ValueObjects\AccessLog\{State, Type};

$accessLogService = new AccessLogService(config: Config::factory());
$accessLogService->create(
    userId: new UserId(1),
    type: new Type('vms2-ping'),
    origin: new Origin('test.locr.com'),
    state: new State('successful'),
    meta: ['foo' => 'bar']
);

3.4. TileAccess

3.4.1. Eintrag erstellen

<?php

use Locr\Lib\UserClient\Services\{Config, TileAccessService};
use Locr\Lib\UserClient\ValueObjects\{Id, Origin, UserId};
use Locr\Lib\UserClient\ValueObjects\TileAccess\Count;

$tileAccessService = new TileAccessService(config: Config::factory());
$tileAccess = $tileAccessService->create(
    userId: new UserId(1),
    origin: new Origin('local.users.locr.com'),
    dateTimeBegin: new \DateTimeImmutable('2024-01-01 00:00:00'),
    dateTimeEnd: new \DateTimeImmutable('2024-01-01 01:00:00'),
    count: new Count(238),
    apiKeyId: new Id(1) // optional
);

3.5. Globale abfragen

3.5.1. Alle Benutzer holen (API-Konfiguration mit http-auth muss richtig eingestellt sein)

<?php

use Locr\Lib\UserClient\Services\{Config, UsersService};

$config = Config::factory();
$usersService = new UsersService(config: $config);
$users = $usersService->getUsers();

3.5.2. Alle Api-Keys holen (API-Konfiguration mit http-auth muss richtig eingestellt sein)

<?php

use Locr\Lib\UserClient\Services\{ApiKeysService, Config};

$config = Config::factory();
$apiKeysService = new ApiKeysService(config: $config);
$users = $apiKeysService->getApiKeys();

4. Verwendung und verhalten der Config-Klasse

4.1. Aufrufe, mit identischem Ergebnis

<?php

use Locr\Lib\UserClient\Services\Config;

$config = Config::factory();

ist dasselbe wie

<?php

use Locr\Lib\UserClient\Implementations\{EnvironmentConfigLoader, IniFileConfigLoader};
use Locr\Lib\UserClient\Services\Config;

$config = Config::factory([
    new IniFileConfigLoader(iniFile: '/etc/locr/user-client.ini'), // .ini-Datei muss vorhanden sein!
    new EnvironmentConfigLoader()
]);

oder

<?php

use Locr\Lib\UserClient\Implementations\{EnvironmentConfigLoader, IniFileConfigLoader};
use Locr\Lib\UserClient\Services\Config;

$config = new Config();
$config
    ->addLoader(new IniFileConfigLoader(iniFile: '/etc/locr/user-client.ini'))
    ->addLoader(new EnvironmentConfigLoader());

4.2. Verhalten bei der Reihenfolge der ConfigLoader

Die ConfigLoader, die später hinzugefügt werden, überschreiben die Werte der vorher hinzugefügten ConfigLoader.

4.3. Der ArrayConfigLoader

<?php

use Locr\Lib\UserClient\Implementations\ArrayConfigLoader;
use Locr\Lib\UserClient\Services\Config;

$config = Config::factory([
    new ArrayConfigLoader([
        'API' => [
            'endpoint' => 'https://users.locr.com/api/'
        ],
        'JWT' => [
            'audience' => 'https://maps.locr.com/'
        ],
        'TOKEN' => [
            'type' => 'jwt',
        ]
    ])
]);

5. Konfigurationsmöglichkeiten, siehe Konfiguration