README

Framework-unabhaengiger, PSR-18-basierter bexio API Client fuer PHP mit vollstaendiger, aus der offiziellen bexio-Dokumentation generierter API-Oberflaeche.

Status

Das Projekt ist bewusst als Neubau gestartet. Die Entscheidung dazu ist dokumentiert in docs/analysis/fork-vs-rebuild.md. Die API-Oberflaeche umfasst aktuell 318 dokumentierte HTTP-Operationen in 58 Ressourcenklassen, generiert aus der offiziellen bexio-Dokumentation.

Installation

composer require crademaker/bexio-api-client

Für eine konkrete HTTP-Implementierung brauchst du zusätzlich einen PSR-18-Client und PSR-17-Fabriken, zum Beispiel mit Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Schnellstart mit Personal Access Token

<?php

declare(strict_types=1);

use Crademaker\BexioApiClient\Auth\StaticTokenProvider;
use Crademaker\BexioApiClient\Http\BexioClient;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;

$httpClient = new GuzzleClient();
$httpFactory = new HttpFactory();

$client = new BexioClient(
    $httpClient,
    $httpFactory,
    $httpFactory,
    new StaticTokenProvider('your-personal-access-token'),
);

$contacts = $client->contacts()->v2ListContacts([
    'limit' => 20,
]);

Vollstaendige API-Oberflaeche

Die Ressourcenzugriffe orientieren sich an den offiziellen Tags der bexio-Dokumentation. Beispiele:

• $client->contacts()
• $client->invoices()
• $client->files()
• $client->projects()
• $client->qrPayments()

Die Methoden orientieren sich an den offiziellen operationIds der Doku. Beispiele:

$contact = $client->contacts()->v2ShowContact([
    'contact_id' => 123,
]);

$matches = $client->contacts()->v2SearchContact(
    [
        [
            'field' => 'name_1',
            'value' => 'Example Company',
            'criteria' => '=',
        ],
    ],
    ['limit' => 20],
);

$created = $client->files()->v3CreateFile(
    [
        'name' => 'example.pdf',
        'file' => [
            'contents' => file_get_contents('/path/to/example.pdf'),
            'filename' => 'example.pdf',
            'content_type' => 'application/pdf',
        ],
    ],
);

Signaturmuster:

• Operation ohne Path- und Body-Parameter: method(array $query = [], array $headers = [])
• Operation mit Path-Parametern: method(array $path, array $query = [], array $headers = [])
• Operation mit Body: method(array $body, array $query = [], array $headers = [])
• Operation mit Path und Body: method(array $path, array $body, array $query = [], array $headers = [])

Die vollstaendige Resource- und Methodenliste steht in docs/api/endpoint-catalog.md.

Implementierungsbeispiele

• Beispiele: examples
• Begleitdoku: docs/usage/implementation-examples.md

OAuth2 / Refresh Tokens

<?php

declare(strict_types=1);

use Crademaker\BexioApiClient\Auth\InMemoryTokenStore;
use Crademaker\BexioApiClient\Auth\OAuthTokenService;
use Crademaker\BexioApiClient\Auth\RefreshableTokenProvider;
use Crademaker\BexioApiClient\Auth\TokenSet;
use Crademaker\BexioApiClient\Http\BexioClient;
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;

$httpClient = new GuzzleClient();
$httpFactory = new HttpFactory();

$tokenStore = new InMemoryTokenStore(
    new TokenSet(
        accessToken: 'initial-access-token',
        refreshToken: 'refresh-token',
    ),
);

$oauth = new OAuthTokenService($httpClient, $httpFactory, $httpFactory);
$provider = new RefreshableTokenProvider(
    clientId: 'client-id',
    clientSecret: 'client-secret',
    tokenStore: $tokenStore,
    tokenService: $oauth,
    scopes: ['openid', 'offline_access', 'contact_show'],
);

$client = new BexioClient($httpClient, $httpFactory, $httpFactory, $provider);

Eine Authorization URL für den initialen Consent-Flow kann so erzeugt werden:

$authorizationUrl = $oauth->buildAuthorizationUrl(
    clientId: 'client-id',
    redirectUri: 'https://app.example.com/callback',
    scopes: ['openid', 'offline_access', 'contact_show'],
    state: 'csrf-token',
);

Fehlerbehandlung

Der Client mappt API-Fehler auf eigene Exceptions:

• AuthenticationException
• AuthorizationException
• ValidationException
• NotFoundException
• RateLimitException
• ServerException
• ApiException
• TransportException

Architektur

• Analyse: docs/analysis/fork-vs-rebuild.md
• Zielarchitektur: docs/architecture/target-architecture.md
• Roadmap: docs/roadmap/endpoint-roadmap.md
• API-Katalog: docs/api/endpoint-catalog.md
• Implementierungsbeispiele: docs/usage/implementation-examples.md
• Mitarbeit / Regeneration: CONTRIBUTING.md

Qualitätssicherung

composer validate --strict
composer test
composer analyse
composer cs:check