Skip to content

Fix: Add getList, refactor and optimize #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pitw merged 1 commit into from
Jun 25, 2025
Merged

Fix: Add getList, refactor and optimize #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 111 additions & 109 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,204 +1,206 @@


# PHP Wrapper für PROFFIX REST-API

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

![alt text](https://raw.githubusercontent.com/pitwch/php-wrapper-proffix-restapi/master/php-wrapper-proffix-rest.jpg "PHP Wrapper PROFFIX REST API")

### Installation
Der Wrapper kann entweder geklont oder via [Composer](https://getcomposer.org) installiert werden.
## Installation

Der Wrapper kann via [Composer](https://getcomposer.org) installiert werden.

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

## Konfiguration

#### Variante 1: Verwendung mit Composer (empfohlen)

### Initialisierung

Autoload RestAPIWrapperProffix class:
Autoload der `RestAPIWrapperProffix` Klasse:

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

use Pitwch\RestAPIWrapperProffix\Client;

```


#### Konfiguration

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 | Names des Benutzers |
| apiPassword | b62cce2fe18f7a156a9c...0f0d7bd18d9e8a40be2e663017 | SHA256-Hash des Benutzerpasswortes |
| apiModule | ADR,STU | Benötigte Module (mit Komma getrennt) |
| options | array('key'=>'112a5a90...59028') | Optionen (Details unter Optionen) |
| 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

Beispiel:
```php

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

use Pitwch\RestAPIWrapperProffix\Client;

$pxrest = new Client(
$pxrest = new Client(
'https://myserver.ch:999',
'DEMO',
'USR',
'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
'ADR,STU',
array('key'=>'112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028','limit'=>2));
$adressen = $pxrest->get('ADR/Adresse',array('filter'=>'GeaendertAm>d\'2018-05-17 14:54:56\'','depth'=>1,'fields'=>'AdressNr,Name,GeaendertAm'));;
['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

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

| Option | Beispiel | Bemerkung |
|------------------|------------------------------------------------------------------|----------------------------------------------------------------|
| key | 112a5a90fe28b...242b10141254b4de59028 | 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 |
| 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 |

#### Methoden
## 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: array("Name"=>"Demo AG",...) |
| parameters | array | Parameter gemäss [PROFFIX REST API Docs](http://www.proffix.net/Portals/0/content/REST%20API/index.html) |

| 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](http://www.proffix.net/Portals/0/content/REST%20API/index.html) |

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

```php
//Escape ' with \'
array('filter'=>'GeaendertAm>d\'2018-05-17 14:54:56\'','depth'=>1,'fields'=>'AdressNr,Name,GeaendertAm')
// 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

Folgende unterschiedlichen Methoden sind mit dem Wrapper möglich:

```php
// 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);
```

##### Get / Query
#### Put / Update

```php
//Einfache Abfrage
$pxrest = new Client(...)
$adresse = $pxrest->get("ADR/Adresse/1") //Legt Response als Objects in $adresse ab
$adresse->Name //DEMO AG

/Abfrage mit Parametern
$pxrest = new Client(...)
$adresse = $pxrest->get("ADR/Adresse",array('filter'=>'GeaendertAm>d\'2018-05-17 14:54:56\'','depth'=>1,'fields'=>'AdressNr,Name,GeaendertAm','limit'=>5))

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


##### Put / Update
#### Post / Create

```php
$pxrest = new Client(...)
$data = array("AdressNr"=>1,"Ort"=>"Zürich","PLZ"=>8000,"EMail"=>"test@test.com");
$adresse = $pxrest->put("ADR/Adresse",$data) //Sendet $data an Endpunkt ADR/Adresse
$data = ["Ort"=>"Zürich", "PLZ"=>8000, "EMail"=>"test@test.com"];
$neueAdresse = $pxrest->post("ADR/Adresse", $data);
```

##### Post / Create
#### Delete

```php
$pxrest = new Client(...)
$data = array("AdressNr"=>1,"Ort"=>"Zürich","PLZ"=>8000,"EMail"=>"test@test.com");
$adresse = $pxrest->post("ADR/Adresse",$data) //Sendet $data an Endpunkt ADR/Adresse
$response = $pxrest->delete("ADR/Adresse/42");
```

### Spezifische Methoden

##### Response / Antwort
#### `getList(int $listenr, array $body = [])`

Alle Methoden geben die Response als Array bzw. NULL (z.B. bei DELETE)
Bei Fehlern wird `HttpClientException` mit Rückmeldung der PROFFIX REST-API ausgegeben.
Generiert eine PROFFIX-Liste (z.B. ein PDF) und gibt das Ergebnis als `Response`-Objekt zurück, welches den rohen Dateiinhalt enthält.

Zudem lassen sich Zusatzinformationen zur Response wie folgt ausgeben:
| 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. |

```php
$pxrest = new Client(...)
$adresse = $pxrest->get("ADR/Adresse")

//Zusatzinformationen zum letzten 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).
*Beispiel:*

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

//Zusatzinformationen zur letzten Response
$lastResponse = $pxrest->http->getResponse();
$lastResponse->getCode(); // Response code (int).
$lastResponse->getHeaders(); // Response headers (array).
$lastResponse->getBody(); // Response body (JSON).
if ($pdfResponse->getCode() === 200) {
file_put_contents('Adressliste.pdf', $pdfResponse->getBody());
echo "Liste erfolgreich als Adressliste.pdf gespeichert.";
}
```

## Spezielle Endpunkte

#### Spezielle Endpunkte

### Info

##### Info
Ruft Infos vom Endpunkt `PRO/Info` ab.

Ruft Infos vom Endpunkt **PRO/Info** ab.

*Hinweis: Dieser Endpunkt / Abfrage blockiert keine Lizenz*
*Hinweis: Dieser Endpunkt / Abfrage blockiert keine Lizenz.*

```php
$pxrest = new Client(...)

//Variante 1: API - Key direkt mitgeben
// Variante 1: API-Key direkt mitgeben
$info1 = $pxrest->info('112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028');

//Variante 2: API - Key aus Options verwenden (sofern dort hinterlegt)
// Variante 2: API-Key aus Options verwenden (sofern dort hinterlegt)
$info2 = $pxrest->info();
```

##### Datenbank
### Datenbank

Ruft Infos vom Endpunkt `PRO/Datenbank` ab.

```php
$dbInfo = $pxrest->database();
```

## Response / Antwort

Ruft Infos vom Endpunkt **PRO/Datenbank** ab.
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.

*Hinweis: Dieser Endpunkt / Abfrage blockiert keine Lizenz*
Zudem lassen sich Zusatzinformationen zur letzten Response wie folgt ausgeben:

### Letzter Request

```php
$pxrest = new Client(...);
$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).
```

//Variante 1: API - Key direkt mitgeben
$datenbank1 = $pxrest->database('112a5a90fe28b23ed2c776562a7d1043957b5b79fad242b10141254b4de59028');

//Variante 2: API - Key aus Options verwenden (sofern dort hinterlegt)
$datenbank2 = $pxrest->database();
```
### Ausnahmen / Spezialfälle
### Letzte Response

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

* Endpunkte welche Leerschläge enthalten können (z.B. LAG/Artikel/PC 7/Bestand) müssen mit rawurlencode() genutzt werden
## Ausnahmen / Spezialfälle

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

Im Ordner [/examples](https://github.com/pitwch/php-wrapper-proffix-restapi/tree/master/examples) finden sich weitere,
auskommentierte Beispiele.
## Weitere Beispiele

Im Ordner [/examples](https://github.com/pitwch/php-wrapper-proffix-restapi/tree/master/examples) finden sich weitere auskommentierte Beispiele.

# Weitere Wrapper für die Proffix Rest-API
## Weitere Wrapper für die Proffix Rest-API

- [Golang Wrapper für die Proffix Rest-API](https://github.com/pitwch/go-wrapper-proffix-restapi) :link:
- [Dart Wrapper für die Proffix Rest-API](https://github.com/pitwch/dart_proffix_rest) :link:
* [Golang Wrapper für die Proffix Rest-API](https://github.com/pitwch/go-wrapper-proffix-restapi)
* [Dart Wrapper für die Proffix Rest-API](https://github.com/pitwch/dart_proffix_rest)
5 changes: 2 additions & 3 deletions composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "pitwch/rest-api-wrapper-proffix-php",
"description": "PHP Wrapper for PROFFIX REST API",
"type": "library",
"version": "1.9.1",
"version": "1.9.2",
"homepage": "https://www.pitw.ch",
"license": "MIT",
"authors": [
Expand All @@ -28,8 +28,7 @@
},
"autoload-dev": {
"psr-4": {
"Pitwch\\RestAPIWrapperProffix\\Tests\\": "tests/RestAPIWrapperProffix/",
"Pitwch\\RestAPIWrapperProffix\\Tests\\Integration\\": "tests/Integration/"
"Pitwch\\RestAPIWrapperProffix\\Tests\\": "tests/"
}
}
}
16 changes: 8 additions & 8 deletions composer.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading