README

Ein effizienter PHP Wrapper für die PROFFIX REST-API.

Installation

Der Wrapper kann via Composer installiert werden.

composer require pitwch/rest-api-wrapper-proffix-php

Konfiguration

Initialisierung

Autoload der RestAPIWrapperProffix Klasse:

require __DIR__ . '/vendor/autoload.php';

use Pitwch\RestAPIWrapperProffix\Client;

Die Konfiguration wird dem Client mitgegeben:

Konfiguration	Beispiel	Bemerkung
url	`https://myserver.ch:999`	URL der REST-API ohne pxapi/v2/
apiDatabase	`DEMO`	Name der Datenbank
apiUser	`USR`	Name des Benutzers
apiPassword	`b62cce2fe18f7a156a9c...`	SHA256-Hash des Benutzerpasswortes
apiModule	`ADR,STU`	Benötigte Module (mit Komma getrennt)
options	`array('key'=>'112a5a90...')`	Optionen (Details unter Optionen)

Beispiel für die Initialisierung

require __DIR__ . '/vendor/autoload.php';

use Pitwch\RestAPIWrapperProffix\Client;

$pxrest = new Client(
    'https://myserver.ch:999',
    'DEMO',
    'USR',
    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
    'ADR,STU',
    ['key'=>'112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028','limit'=>2]
);

$adressen = $pxrest->get('ADR/Adresse', ['filter'=>'GeaendertAm>d\'2018-05-17 14:54:56\'', 'depth'=>1, 'fields'=>'AdressNr,Name,GeaendertAm']);
print_r($adressen);

Optionen

Optionen sind fakultativ und werden in der Regel nicht benötigt:

Option	Beispiel	Bemerkung
key	`112a5a90fe28b...`	API-Key als SHA256 - Hash (kann auch direkt mitgegeben werden)
version	`v2`	API-Version; Standard = v2
api_prefix	`/pxapi/`	Prefix für die API; Standard = /pxapi/
login_endpoint	`PRO/Login`	Endpunkt für Login; Standard = PRO/Login
user_agent	`php-wrapper-proffix-restapi`	User Agent; Standard = php-wrapper-proffix-restapi
timeout	`15`	Timeout für Curl in Sekunden; Standard = 15
follow_redirects	`true`	Weiterleitungen der API folgen; Standard = false
enable_session_caching	`true`	Session-Caching aktivieren; Standard = true
cache_dir	`/tmp/proffix-cache`	Eigenes Cache-Verzeichnis; Standard = plattformspezifisch

Session-Caching

Der Wrapper unterstützt automatisches Session-Caching, um die Performance zu verbessern und die Anzahl der Login-Requests zu reduzieren. Das Session-Caching ist standardmässig aktiviert.

Funktionsweise:

Nach einem erfolgreichen Login wird die PxSessionId in einer Datei gespeichert
Bei nachfolgenden Requests wird zuerst versucht, die gespeicherte Session zu laden
Bei ungültigen Sessions (401-Fehler) wird automatisch ein neuer Login durchgeführt
Sessions werden automatisch beim Logout oder bei Fehlern gelöscht

Cache-Speicherort:

Der Cache-Speicherort kann über die Option cache_dir angepasst werden. Dies ist besonders nützlich bei Hosting-Umgebungen mit open_basedir-Einschränkungen.

Standard-Speicherorte (wenn cache_dir nicht angegeben):

Windows: %APPDATA%/php-wrapper-proffix-restapi/
Linux/Mac: ~/.cache/php-wrapper-proffix-restapi/ oder /tmp/php-wrapper-proffix-restapi/

Der Dateiname wird aus Benutzername, Datenbank und URL generiert, um Konflikte bei mehreren Clients zu vermeiden.

Eigenes Cache-Verzeichnis verwenden:

$pxrest = new Client(
    'https://myserver.ch:999',
    'DEMO',
    'USR',
    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
    'ADR,STU',
    [
        'enable_session_caching' => true,
        'cache_dir' => '/tmp/proffix-cache'  // Eigenes Verzeichnis
    ]
);

Empfohlene Cache-Verzeichnisse für verschiedene Umgebungen:

// Shared Hosting (z.B. Plesk) mit open_basedir-Einschränkungen
'cache_dir' => '/tmp/proffix-cache'

// Cross-Platform (empfohlen)
'cache_dir' => sys_get_temp_dir() . '/proffix-cache'

// Innerhalb des Projekts
'cache_dir' => __DIR__ . '/cache'

Technische Details:

Die Session-Verwaltung erfolgt über die SessionCache-Klasse (src/RestAPIWrapperProffix/HttpClient/SessionCache.php), die folgende Funktionen bietet:

load(): Lädt eine gespeicherte Session-ID aus dem Cache
save($sessionId): Speichert eine Session-ID im Cache
clear(): Löscht die gespeicherte Session-ID
Unterstützung für eigene Cache-Verzeichnisse (Option cache_dir)
Automatische Erkennung des plattformspezifischen Cache-Verzeichnisses
Thread-sichere Dateioperationen mit LOCK_EX
Kollisionsvermeidung durch Base64-URL-kodierte Dateinamen

Cache-Verzeichnis-Priorität:

Eigenes Verzeichnis (wenn cache_dir Option gesetzt)
Plattformspezifische Standard-Verzeichnisse
Fallback auf /tmp/ oder sys_get_temp_dir()

Session-Caching deaktivieren:

$pxrest = new Client(
    'https://myserver.ch:999',
    'DEMO',
    'USR',
    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
    'ADR,STU',
    ['enable_session_caching' => false]
);

Methoden

Allgemeine Methoden (`get`, `put`, `post`, `delete`)

Parameter	Typ	Bemerkung
endpoint	`string`	Endpunkt der PROFFIX REST-API; z.B. `ADR/Adresse`, `STU/Rapporte`...
data	`array`	Daten (werden automatisch in JSON konvertiert); z.B: `["Name"=>"Demo AG",...]`
parameters	`array`	Parameter gemäss PROFFIX REST API Docs

Sonderzeichen in den Parametern müssen gegebenfalls mit Escape-Zeichen verwendet werden, z.B:

// Escape ' with \'
$params = ['filter' => 'GeaendertAm>d\'2018-05-17 14:54:56\'', 'depth' => 1, 'fields' => 'AdressNr,Name,GeaendertAm'];
$pxrest->get('ADR/Adresse', $params);

Get / Query

// Einfache Abfrage
$adresse = $pxrest->get("ADR/Adresse/1");
echo $adresse->Name; // DEMO AG

// Abfrage mit Parametern
$params = ['filter'=>'GeaendertAm>d\'2018-05-17 14:54:56\'','depth'=>1,'fields'=>'AdressNr,Name,GeaendertAm','limit'=>5];
$adressen = $pxrest->get("ADR/Adresse", $params);

Put / Update

$data = ["AdressNr"=>1, "Ort"=>"Zürich", "PLZ"=>8000, "EMail"=>"test@test.com"];
$adresse = $pxrest->put("ADR/Adresse", $data);

Post / Create

$data = ["Ort"=>"Zürich", "PLZ"=>8000, "EMail"=>"test@test.com"];
$neueAdresse = $pxrest->post("ADR/Adresse", $data);

Delete

$response = $pxrest->delete("ADR/Adresse/42");

Spezifische Methoden

`getList(int $listenr, array $body = [])`

Generiert eine PROFFIX-Liste (z.B. ein PDF) und gibt das Ergebnis als Response-Objekt zurück, welches den rohen Dateiinhalt enthält.

Parameter	Typ	Bemerkung
`$listenr`	`int`	Die `ListeNr` der Liste, die generiert werden soll.
`$body`	`array`	(Optional) Ein assoziatives Array mit Parametern für die Listengenerierung. Wichtig: Es muss mindestens ein leeres JSON-Objekt (`{}`) gesendet werden.

Beispiel:

$listeNr = 1029; // Beispiel-ID für ADR_Adressliste.repx
$pdfResponse = $pxrest->getList($listeNr);

if ($pdfResponse->getCode() === 200) {
    file_put_contents('Adressliste.pdf', $pdfResponse->getBody());
    echo "Liste erfolgreich als Adressliste.pdf gespeichert.";
}

Spezielle Endpunkte

Info

Ruft Infos vom Endpunkt PRO/Info ab.

Hinweis: Dieser Endpunkt / Abfrage blockiert keine Lizenz.

// Variante 1: API-Key direkt mitgeben
$info1 = $pxrest->info('112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028');
  
// Variante 2: API-Key aus Options verwenden (sofern dort hinterlegt)
$info2 = $pxrest->info();

Datenbank

Ruft Infos vom Endpunkt PRO/Datenbank ab.

$dbInfo = $pxrest->database();

Response / Antwort

Alle Methoden geben die Response als Array bzw. NULL (z.B. bei DELETE) zurück. Bei Fehlern wird eine HttpClientException mit der Rückmeldung der PROFFIX REST-API geworfen.

Error Handling

Der Wrapper bietet erweitertes Error Handling, das sowohl allgemeine Fehlermeldungen als auch feldspezifische Validierungsfehler erfasst.

Beispiel einer PROFFIX API Fehlerantwort

{
  "Fields": [
    {
      "Reason": "EMPTY",
      "Name": "PLZ",
      "Message": "PLZ darf nicht leer bleiben!"
    },
    {
      "Reason": "EMPTY",
      "Name": "Land",
      "Message": "Land darf nicht leer bleiben!"
    }
  ],
  "Message": "Mindestens ein Feld ist ungültig."
}

Fehlerbehandlung mit HttpClientException

use Pitwch\RestAPIWrapperProffix\HttpClient\HttpClientException;

try {
    $data = ["Ort" => "Zürich", "PLZ" => "", "Land" => ""];
    $neueAdresse = $pxrest->post("ADR/Adresse", $data);
} catch (HttpClientException $e) {
    // Hauptfehlermeldung
    echo "Fehler: " . $e->getMessage() . "\n";
    // "Mindestens ein Feld ist ungültig."
    
    // Prüfen, ob feldspezifische Fehler vorhanden sind
    if ($e->hasFieldErrors()) {
        echo "Feldvalidierungsfehler:\n";
        
        foreach ($e->getFieldErrors() as $error) {
            echo sprintf(
                "  - %s: %s (Grund: %s)\n",
                $error['Name'],
                $error['Message'],
                $error['Reason']
            );
        }
        
        // Oder alle Details als formatierte Nachricht
        echo "\n" . $e->getDetailedMessage();
    }
}

Verfügbare Methoden:

getMessage(): Gibt die Hauptfehlermeldung zurück
hasFieldErrors(): Prüft, ob feldspezifische Fehler vorhanden sind
getFieldErrors(): Gibt ein Array mit allen Feldfehlern zurück
getDetailedMessage(): Gibt eine formatierte Nachricht mit allen Fehlerdetails zurück
getCode(): Gibt den HTTP-Statuscode zurück
getRequest(): Gibt das Request-Objekt zurück
getResponse(): Gibt das Response-Objekt zurück

Weitere Details und Beispiele finden sich in der Error Handling Dokumentation.

Zusatzinformationen zur Response

Zudem lassen sich Zusatzinformationen zur letzten Response wie folgt ausgeben:

Letzter Request

$lastRequest = $pxrest->http->getRequest();
$lastRequest->getUrl(); // Get requested URL (string).
$lastRequest->getMethod(); // Get request method (string).
$lastRequest->getParameters(); // Get request parameters (array).
$lastRequest->getHeaders(); // Get request headers (array).
$lastRequest->getBody(); // Get request body (JSON).

Letzte Response

$lastResponse = $pxrest->http->getResponse();
$lastResponse->getCode(); // Response code (int).
$lastResponse->getHeaders(); // Response headers (array).
$lastResponse->getBody(); // Response body (JSON).

Ausnahmen / Spezialfälle

Endpunkte, welche Leerschläge enthalten (z.B. LAG/Artikel/PC 7/Bestand), müssen mit rawurlencode() genutzt werden.

Weitere Beispiele

Im Ordner /examples finden sich weitere auskommentierte Beispiele.

pitwch / rest-api-wrapper-proffix-php

Maintainers

Details

README

Installation

Konfiguration

Initialisierung

Beispiel für die Initialisierung

Optionen

Session-Caching

Methoden

Allgemeine Methoden (`get`, `put`, `post`, `delete`)

Get / Query

Put / Update

Post / Create

Delete

Spezifische Methoden

`getList(int $listenr, array $body = [])`

Spezielle Endpunkte

Info

Datenbank

Response / Antwort

Error Handling

Beispiel einer PROFFIX API Fehlerantwort

Fehlerbehandlung mit HttpClientException

Zusatzinformationen zur Response

Letzter Request

Letzte Response

Ausnahmen / Spezialfälle

Weitere Beispiele

Weitere Wrapper für die Proffix Rest-API

pitwch / rest-api-wrapper-proffix-php

Maintainers

Details

README

Installation

Konfiguration

Initialisierung

Beispiel für die Initialisierung

Optionen

Session-Caching

Methoden

Allgemeine Methoden (get, put, post, delete)

Get / Query

Put / Update

Post / Create

Delete

Spezifische Methoden

getList(int $listenr, array $body = [])

Spezielle Endpunkte

Info

Datenbank

Response / Antwort

Error Handling

Beispiel einer PROFFIX API Fehlerantwort

Fehlerbehandlung mit HttpClientException

Zusatzinformationen zur Response

Letzter Request

Letzte Response

Ausnahmen / Spezialfälle

Weitere Beispiele

Weitere Wrapper für die Proffix Rest-API

Allgemeine Methoden (`get`, `put`, `post`, `delete`)

`getList(int $listenr, array $body = [])`