# Anleitung — omsorgcore-client-php

Generierter PHP-Client für die `omsorgCore`-API, erzeugt mit [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator) aus der Swagger/OpenAPI-JSON des Backends. **Ersetzt (noch) nicht** den handgeschriebenen Wrapper `lib/omsorgCoreClient.php` (reiner cURL-Wrapper, eigenes Rückgabeformat `['ok', 'status', 'data']`) — der bleibt unverändert im Einsatz. Dieser Client ist eine zusätzliche, eigenständige Bibliothek.

`README.md` in diesem Ordner wird bei jeder Generierung automatisch neu geschrieben (Standard-Output von openapi-generator, dokumentiert die generierten API-Klassen) — diese Datei hier nicht, sie bleibt stabil.

## Voraussetzungen

- Node.js + npx (für `openapi-generator-cli`, keine separate Node-Installation im restlichen `omsorgWeb` nötig — nur für die Generierung selbst)
- Java (wird von `openapi-generator-cli` intern benötigt, `java` muss im `PATH` sein)
- **Composer** (für den generierten PHP-Client — im Gegensatz zum Rest von `omsorgWeb`, das bewusst framework-/Composer-frei ist. Installation z. B. `sudo apt install composer` oder offizielles Installer-Skript von [getcomposer.org](https://getcomposer.org/download/))
- `omsorgCore` muss lokal im **Development-Modus** laufen, da Swagger nur dort aktiv ist

## API lokal starten (für die Generierung)

```bash
cd omsorgCore
ASPNETCORE_ENVIRONMENT=Development dotnet run --project src/OmsorgCore.Api
# → Swagger-JSON unter http://localhost:5245/swagger/v1/swagger.json
```

## Client neu generieren

```bash
cd omsorgWeb/mitarbeiter-app/api-client-php
./generate.sh
```

Nimmt die Backend-URL aus `OMSORG_CORE_URL` (Default `http://localhost:5245`, dieselbe Konvention wie `OMSORG_CORE_URL` in `omsorgapp` bzw. die Basis-URL in `lib/omsorgCoreClient.php`). Überschreibt `lib/`, `docs/`, `test/`, `README.md`, `composer.json`, `.gitignore` mit dem aktuellen generierten Stand — danach `git diff` prüfen, bevor committet wird.

## Abhängigkeiten installieren

```bash
composer install
```

Installiert u. a. `guzzlehttp/guzzle` (HTTP-Client, vom generierten Code genutzt) nach `vendor/`. `vendor/` ist `.gitignore`'t — nur der generierte Quellcode unter `lib/` wird eingecheckt.

## Verwendung (Beispiel)

```php
<?php
require_once __DIR__ . '/api-client-php/vendor/autoload.php';

$config = OmsorgCoreClient\Configuration::getDefaultConfiguration()
    ->setHost(getenv('OMSORG_CORE_URL') ?: 'http://localhost:5245');

$authApi = new OmsorgCoreClient\Api\AuthApi(new GuzzleHttp\Client(), $config);

$loginRequest = new OmsorgCoreClient\Model\LoginRequest([
    'username' => 'admin',
    'password' => 'abersicher',
]);

$loginResponse = $authApi->apiAuthLoginPost($loginRequest);
echo $loginResponse->getAccessToken();
```

Jeder Controller aus `omsorgCore` hat eine eigene `Api`-Klasse unter `OmsorgCoreClient\Api\` (`AuthApi`, `EmployeesApi`, `FacilitiesApi`, `ContractsApi`, `OrdersApi`, `RolesApi`, `UsersApi`, `ValueListsApi`, `AuditLogApi`, `AdminSessionsApi`, `AdminEmailApi`, `HealthApi`) — siehe `docs/Api/` für die vollständige Methodenliste je Klasse. (Namespace ist `OmsorgCoreClient`, nicht `OmsorgCore\Client` — das `\\`-Escaping im `invokerPackage`-Parameter von `generate.sh` wurde vom Generator beim ersten Lauf nicht wie erwartet aufgelöst, siehe `composer.json`s `psr-4`-Mapping.)

## Wichtig: nach Backend-Änderungen

Sobald sich Controller/DTOs in `omsorgCore` ändern (neue Endpunkte, neue Felder in Requests/Responses), sollte dieser Client neu generiert und der Diff mitcommittet werden — sonst driftet er unbemerkt vom tatsächlichen Backend-Vertrag ab.