{"id":46087828,"url":"https://github.com/pitwch/php-wrapper-proffix-restapi","last_synced_at":"2026-03-01T17:02:50.425Z","repository":{"id":57041956,"uuid":"130210878","full_name":"pitwch/php-wrapper-proffix-restapi","owner":"pitwch","description":"PHP Wrapper für die PROFFIX REST API","archived":false,"fork":false,"pushed_at":"2025-11-11T14:49:05.000Z","size":932,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-11T16:24:17.628Z","etag":null,"topics":["proffix","rest","rest-api","rest-client","restful-api","wrapper-api"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pitwch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG_SESSION_CACHING.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-04-19T12:16:42.000Z","updated_at":"2025-11-11T14:49:09.000Z","dependencies_parsed_at":"2025-06-18T15:22:09.044Z","dependency_job_id":"a031dc69-072e-43dd-be27-8bf229213692","html_url":"https://github.com/pitwch/php-wrapper-proffix-restapi","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/pitwch/php-wrapper-proffix-restapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitwch%2Fphp-wrapper-proffix-restapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitwch%2Fphp-wrapper-proffix-restapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitwch%2Fphp-wrapper-proffix-restapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitwch%2Fphp-wrapper-proffix-restapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pitwch","download_url":"https://codeload.github.com/pitwch/php-wrapper-proffix-restapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitwch%2Fphp-wrapper-proffix-restapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29976272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:35:47.903Z","status":"ssl_error","status_checked_at":"2026-03-01T16:35:44.899Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["proffix","rest","rest-api","rest-client","restful-api","wrapper-api"],"created_at":"2026-03-01T17:02:49.617Z","updated_at":"2026-03-01T17:02:50.419Z","avatar_url":"https://github.com/pitwch.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Wrapper für PROFFIX REST-API\n\nEin effizienter PHP Wrapper für die PROFFIX REST-API.\n\n![alt text](https://raw.githubusercontent.com/pitwch/php-wrapper-proffix-restapi/master/php-wrapper-proffix-rest.jpg \"PHP Wrapper PROFFIX REST API\")\n\n## Installation\n\nDer Wrapper kann via [Composer](https://getcomposer.org) installiert werden.\n\n```php\ncomposer require pitwch/rest-api-wrapper-proffix-php\n```\n\n## Konfiguration\n\n### Initialisierung\n\nAutoload der `RestAPIWrapperProffix` Klasse:\n\n```php\nrequire __DIR__ . '/vendor/autoload.php';\n\nuse Pitwch\\RestAPIWrapperProffix\\Client;\n```\n\nDie Konfiguration wird dem Client mitgegeben:\n\n| Konfiguration    | Beispiel                                                                         | Bemerkung                                        |\n|------------------|----------------------------------------------------------------------------------|--------------------------------------------------|\n| url              | `https://myserver.ch:999`                                                        | URL der REST-API **ohne pxapi/v2/**              |\n| apiDatabase      | `DEMO`                                                                           | Name der Datenbank                               |\n| apiUser          | `USR`                                                                            | Name des Benutzers                               |\n| apiPassword      | `b62cce2fe18f7a156a9c...`                                                        | SHA256-Hash des Benutzerpasswortes               |\n| apiModule        | `ADR,STU`                                                                        | Benötigte Module (mit Komma getrennt)            |\n| options          | `array('key'=\u003e'112a5a90...')`                                                    | Optionen (Details unter Optionen)                |\n\n### Beispiel für die Initialisierung\n\n```php\nrequire __DIR__ . '/vendor/autoload.php';\n\nuse Pitwch\\RestAPIWrapperProffix\\Client;\n\n$pxrest = new Client(\n    'https://myserver.ch:999',\n    'DEMO',\n    'USR',\n    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',\n    'ADR,STU',\n    ['key'=\u003e'112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028','limit'=\u003e2]\n);\n\n$adressen = $pxrest-\u003eget('ADR/Adresse', ['filter'=\u003e'GeaendertAm\u003ed\\'2018-05-17 14:54:56\\'', 'depth'=\u003e1, 'fields'=\u003e'AdressNr,Name,GeaendertAm']);\nprint_r($adressen);\n```\n\n## Optionen\n\nOptionen sind **fakultativ** und werden in der Regel nicht benötigt:\n\n| Option                  | Beispiel                               | Bemerkung                                                      |\n|-------------------------|----------------------------------------|----------------------------------------------------------------|\n| key                     | `112a5a90fe28b...`                     | API-Key als SHA256 - Hash (kann auch direkt mitgegeben werden) |\n| version                 | `v2`                                   | API-Version; Standard = v2                                     |\n| api_prefix              | `/pxapi/`                              | Prefix für die API; Standard = /pxapi/                         |\n| login_endpoint          | `PRO/Login`                            | Endpunkt für Login; Standard = PRO/Login                       |\n| user_agent              | `php-wrapper-proffix-restapi`          | User Agent; Standard = php-wrapper-proffix-restapi             |\n| timeout                 | `15`                                   | Timeout für Curl in Sekunden; Standard = 15                    |\n| follow_redirects        | `true`                                 | Weiterleitungen der API folgen; Standard = false               |\n| enable_session_caching  | `true`                                 | Session-Caching aktivieren; Standard = true                    |\n| cache_dir               | `/tmp/proffix-cache`                   | Eigenes Cache-Verzeichnis; Standard = plattformspezifisch      |\n\n### Session-Caching\n\nDer 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**.\n\n**Funktionsweise:**\n\n- Nach einem erfolgreichen Login wird die `PxSessionId` in einer Datei gespeichert\n- Bei nachfolgenden Requests wird zuerst versucht, die gespeicherte Session zu laden\n- Bei ungültigen Sessions (401-Fehler) wird automatisch ein neuer Login durchgeführt\n- Sessions werden automatisch beim Logout oder bei Fehlern gelöscht\n\n**Cache-Speicherort:**\n\nDer Cache-Speicherort kann über die Option `cache_dir` angepasst werden. Dies ist besonders nützlich bei Hosting-Umgebungen mit `open_basedir`-Einschränkungen.\n\n**Standard-Speicherorte** (wenn `cache_dir` nicht angegeben):\n\n- **Windows:** `%APPDATA%/php-wrapper-proffix-restapi/`\n- **Linux/Mac:** `~/.cache/php-wrapper-proffix-restapi/` oder `/tmp/php-wrapper-proffix-restapi/`\n\nDer Dateiname wird aus Benutzername, Datenbank und URL generiert, um Konflikte bei mehreren Clients zu vermeiden.\n\n**Eigenes Cache-Verzeichnis verwenden:**\n\n```php\n$pxrest = new Client(\n    'https://myserver.ch:999',\n    'DEMO',\n    'USR',\n    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',\n    'ADR,STU',\n    [\n        'enable_session_caching' =\u003e true,\n        'cache_dir' =\u003e '/tmp/proffix-cache'  // Eigenes Verzeichnis\n    ]\n);\n```\n\n**Empfohlene Cache-Verzeichnisse für verschiedene Umgebungen:**\n\n```php\n// Shared Hosting (z.B. Plesk) mit open_basedir-Einschränkungen\n'cache_dir' =\u003e '/tmp/proffix-cache'\n\n// Cross-Platform (empfohlen)\n'cache_dir' =\u003e sys_get_temp_dir() . '/proffix-cache'\n\n// Innerhalb des Projekts\n'cache_dir' =\u003e __DIR__ . '/cache'\n```\n\n**Technische Details:**\n\nDie Session-Verwaltung erfolgt über die `SessionCache`-Klasse (`src/RestAPIWrapperProffix/HttpClient/SessionCache.php`), die folgende Funktionen bietet:\n\n- `load()`: Lädt eine gespeicherte Session-ID aus dem Cache\n- `save($sessionId)`: Speichert eine Session-ID im Cache\n- `clear()`: Löscht die gespeicherte Session-ID\n- Unterstützung für eigene Cache-Verzeichnisse (Option `cache_dir`)\n- Automatische Erkennung des plattformspezifischen Cache-Verzeichnisses\n- Thread-sichere Dateioperationen mit `LOCK_EX`\n- Kollisionsvermeidung durch Base64-URL-kodierte Dateinamen\n\n**Cache-Verzeichnis-Priorität:**\n\n1. Eigenes Verzeichnis (wenn `cache_dir` Option gesetzt)\n2. Plattformspezifische Standard-Verzeichnisse\n3. Fallback auf `/tmp/` oder `sys_get_temp_dir()`\n\n**Session-Caching deaktivieren:**\n\n```php\n$pxrest = new Client(\n    'https://myserver.ch:999',\n    'DEMO',\n    'USR',\n    'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',\n    'ADR,STU',\n    ['enable_session_caching' =\u003e false]\n);\n```\n\n## Methoden\n\n### Allgemeine Methoden (`get`, `put`, `post`, `delete`)\n\n| Parameter  | Typ    | Bemerkung                                                                                                |\n|------------|--------|----------------------------------------------------------------------------------------------------------|\n| endpoint   | `string` | Endpunkt der PROFFIX REST-API; z.B. `ADR/Adresse`, `STU/Rapporte`...                                     |\n| data       | `array`  | Daten (werden automatisch in JSON konvertiert); z.B: `[\"Name\"=\u003e\"Demo AG\",...]`                           |\n| parameters | `array`  | Parameter gemäss [PROFFIX REST API Docs](http://www.proffix.net/Portals/0/content/REST%20API/index.html) |\n\n*Sonderzeichen in den Parametern müssen gegebenfalls mit Escape-Zeichen verwendet werden, z.B:*\n\n```php\n// Escape ' with \\'\n$params = ['filter' =\u003e 'GeaendertAm\u003ed\\'2018-05-17 14:54:56\\'', 'depth' =\u003e 1, 'fields' =\u003e 'AdressNr,Name,GeaendertAm'];\n$pxrest-\u003eget('ADR/Adresse', $params);\n```\n\n#### Get / Query\n\n```php\n// Einfache Abfrage\n$adresse = $pxrest-\u003eget(\"ADR/Adresse/1\");\necho $adresse-\u003eName; // DEMO AG\n\n// Abfrage mit Parametern\n$params = ['filter'=\u003e'GeaendertAm\u003ed\\'2018-05-17 14:54:56\\'','depth'=\u003e1,'fields'=\u003e'AdressNr,Name,GeaendertAm','limit'=\u003e5];\n$adressen = $pxrest-\u003eget(\"ADR/Adresse\", $params);\n```\n\n#### Put / Update\n\n```php\n$data = [\"AdressNr\"=\u003e1, \"Ort\"=\u003e\"Zürich\", \"PLZ\"=\u003e8000, \"EMail\"=\u003e\"test@test.com\"];\n$adresse = $pxrest-\u003eput(\"ADR/Adresse\", $data);\n```\n\n#### Post / Create\n\n```php\n$data = [\"Ort\"=\u003e\"Zürich\", \"PLZ\"=\u003e8000, \"EMail\"=\u003e\"test@test.com\"];\n$neueAdresse = $pxrest-\u003epost(\"ADR/Adresse\", $data);\n```\n\n#### Delete\n\n```php\n$response = $pxrest-\u003edelete(\"ADR/Adresse/42\");\n```\n\n### Spezifische Methoden\n\n#### `getList(int $listenr, array $body = [])`\n\nGeneriert eine PROFFIX-Liste (z.B. ein PDF) und gibt das Ergebnis als `Response`-Objekt zurück, welches den rohen Dateiinhalt enthält.\n\n| Parameter | Typ      | Bemerkung                                                                                                                                      |\n|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------|\n| `$listenr`| `int`    | Die `ListeNr` der Liste, die generiert werden soll.                                                                                            |\n| `$body`   | `array`  | (Optional) Ein assoziatives Array mit Parametern für die Listengenerierung. **Wichtig:** Es muss mindestens ein leeres JSON-Objekt (`{}`) gesendet werden. |\n\n*Beispiel:*\n\n```php\n$listeNr = 1029; // Beispiel-ID für ADR_Adressliste.repx\n$pdfResponse = $pxrest-\u003egetList($listeNr);\n\nif ($pdfResponse-\u003egetCode() === 200) {\n    file_put_contents('Adressliste.pdf', $pdfResponse-\u003egetBody());\n    echo \"Liste erfolgreich als Adressliste.pdf gespeichert.\";\n}\n```\n\n## Spezielle Endpunkte\n\n### Info\n\nRuft Infos vom Endpunkt `PRO/Info` ab.\n\n*Hinweis: Dieser Endpunkt / Abfrage blockiert keine Lizenz.*\n\n```php\n// Variante 1: API-Key direkt mitgeben\n$info1 = $pxrest-\u003einfo('112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028');\n  \n// Variante 2: API-Key aus Options verwenden (sofern dort hinterlegt)\n$info2 = $pxrest-\u003einfo();\n```\n\n### Datenbank\n\nRuft Infos vom Endpunkt `PRO/Datenbank` ab.\n\n```php\n$dbInfo = $pxrest-\u003edatabase();\n```\n\n## Response / Antwort\n\nAlle 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.\n\n### Error Handling\n\nDer Wrapper bietet erweitertes Error Handling, das sowohl allgemeine Fehlermeldungen als auch feldspezifische Validierungsfehler erfasst.\n\n#### Beispiel einer PROFFIX API Fehlerantwort\n\n```json\n{\n  \"Fields\": [\n    {\n      \"Reason\": \"EMPTY\",\n      \"Name\": \"PLZ\",\n      \"Message\": \"PLZ darf nicht leer bleiben!\"\n    },\n    {\n      \"Reason\": \"EMPTY\",\n      \"Name\": \"Land\",\n      \"Message\": \"Land darf nicht leer bleiben!\"\n    }\n  ],\n  \"Message\": \"Mindestens ein Feld ist ungültig.\"\n}\n```\n\n#### Fehlerbehandlung mit HttpClientException\n\n```php\nuse Pitwch\\RestAPIWrapperProffix\\HttpClient\\HttpClientException;\n\ntry {\n    $data = [\"Ort\" =\u003e \"Zürich\", \"PLZ\" =\u003e \"\", \"Land\" =\u003e \"\"];\n    $neueAdresse = $pxrest-\u003epost(\"ADR/Adresse\", $data);\n} catch (HttpClientException $e) {\n    // Hauptfehlermeldung\n    echo \"Fehler: \" . $e-\u003egetMessage() . \"\\n\";\n    // \"Mindestens ein Feld ist ungültig.\"\n    \n    // Prüfen, ob feldspezifische Fehler vorhanden sind\n    if ($e-\u003ehasFieldErrors()) {\n        echo \"Feldvalidierungsfehler:\\n\";\n        \n        foreach ($e-\u003egetFieldErrors() as $error) {\n            echo sprintf(\n                \"  - %s: %s (Grund: %s)\\n\",\n                $error['Name'],\n                $error['Message'],\n                $error['Reason']\n            );\n        }\n        \n        // Oder alle Details als formatierte Nachricht\n        echo \"\\n\" . $e-\u003egetDetailedMessage();\n    }\n}\n```\n\n**Verfügbare Methoden:**\n\n- `getMessage()`: Gibt die Hauptfehlermeldung zurück\n- `hasFieldErrors()`: Prüft, ob feldspezifische Fehler vorhanden sind\n- `getFieldErrors()`: Gibt ein Array mit allen Feldfehlern zurück\n- `getDetailedMessage()`: Gibt eine formatierte Nachricht mit allen Fehlerdetails zurück\n- `getCode()`: Gibt den HTTP-Statuscode zurück\n- `getRequest()`: Gibt das Request-Objekt zurück\n- `getResponse()`: Gibt das Response-Objekt zurück\n\nWeitere Details und Beispiele finden sich in der [Error Handling Dokumentation](docs/ERROR_HANDLING.md).\n\n### Zusatzinformationen zur Response\n\nZudem lassen sich Zusatzinformationen zur letzten Response wie folgt ausgeben:\n\n### Letzter Request\n\n```php\n$lastRequest = $pxrest-\u003ehttp-\u003egetRequest();\n$lastRequest-\u003egetUrl(); // Get requested URL (string).\n$lastRequest-\u003egetMethod(); // Get request method (string).\n$lastRequest-\u003egetParameters(); // Get request parameters (array).\n$lastRequest-\u003egetHeaders(); // Get request headers (array).\n$lastRequest-\u003egetBody(); // Get request body (JSON).\n```\n\n### Letzte Response\n\n```php\n$lastResponse = $pxrest-\u003ehttp-\u003egetResponse();\n$lastResponse-\u003egetCode(); // Response code (int).\n$lastResponse-\u003egetHeaders(); // Response headers (array).\n$lastResponse-\u003egetBody(); // Response body (JSON).\n```\n\n## Ausnahmen / Spezialfälle\n\n* Endpunkte, welche Leerschläge enthalten (z.B. `LAG/Artikel/PC 7/Bestand`), müssen mit `rawurlencode()` genutzt werden.\n\n## Weitere Beispiele\n\nIm Ordner [/examples](https://github.com/pitwch/php-wrapper-proffix-restapi/tree/master/examples) finden sich weitere auskommentierte Beispiele.\n\n## Weitere Wrapper für die Proffix Rest-API\n\n* [Golang Wrapper für die Proffix Rest-API](https://github.com/pitwch/go-wrapper-proffix-restapi)\n* [Dart Wrapper für die Proffix Rest-API](https://github.com/pitwch/dart_proffix_rest)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitwch%2Fphp-wrapper-proffix-restapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpitwch%2Fphp-wrapper-proffix-restapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitwch%2Fphp-wrapper-proffix-restapi/lists"}