Integration mit PHP

Mit InterFAX können Sie Ihre eigenen Anwendungen faxfähig machen – ohne separaten Faxserver. Zunächst richten Sie dafür einen Composer ein.

Inhaltsverzeichnis:

 

Einrichtung Composer

  1. Interfax PHP-Repositories in Ihr Projektverzeichnis herunterladen
    (`/var/www/html/PHP_Website` ist hier das neue Projektverzeichnis)
    cd /var/www/html/PHP_Website
    git clone     https://github.com/interfax/interfax-php.git
  2. In das Verzeichnis des Interfax PHP-Repositories wechseln: cd interfax-php
  3. Composer einrichten:
    Composer ist ein Abhängigkeitsmanager für PHP, der die Installation und Verwaltung von Bibliotheken erleichtert.

    1. Erstellen Sie zunächst ein Verzeichnis für den Composer: mkdir bin
    2. Laden Sie das Composer-Installationsskript herunter und führen Sie es aus:
      php -r “copy(‘https://getcomposer.org/installer’, ‘composer-setup.php’);”
      php composer-setup.php –install-dir=bin
      php -r “unlink(‘composer-setup.php’);”
  4. Abhängigkeiten der InterFAX PHP Bibliothek mit Composer installieren:
    php ./bin/composer.phar install –no-dev –ignore-platform-req=ext-simplexml –ignore-platform-req=ext-domDie Parameter `–no-dev`, `–ignore-platform-req=ext-simplexml` und `–ignore-platform-req=ext-dom` sorgen dafür, dass die Entwicklungsabhängigkeiten und bestimmte Plattformanforderungen ignoriert werden.
  5. Interfax Bibliothek in Ihrem Projekt verwenden:
    Durch das Einbinden der Autoload-Datei von Composer und die Initialisierung des Interfax-Clients in Ihrer PHP-Datei, z.B. in `index.php`.

    1. Fügen Sie die folgende Zeile in Ihre PHP-Datei ein, um die Autoload-Datei zu inkludieren: require_once(__DIR__ . ‘/interfax-php/vendor/autoload.php’);
    2. Verwenden Sie anschließend den Interfax-Client wie folgt:
      use Interfax\Client;$interfax = new Client([
      ‘username’ => ‘dein_username’,
      ‘password’ => ‘dein_passwort’
      ]);

PHP-Befehle für die Integration

1. Einrichtung des Clients

$client = new Interfax\Client([‘username’ => ‘…’, ‘password’ => ‘…’]);

// Alternative: Nutzung von Umgebungsvariablen
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD

$client = new Interfax\Client();

Der Client wird mit einem Array initialisiert, das die Schlüssel username und password enthält. Diese Werte sind die Anmeldedaten Ihres Interfax-Kontos und müssen definiert werden.

2. Senden eines Faxes

Um ein Fax zu senden, muss die deliver-Methode des Clients mit den entsprechenden Parametern aufgerufen werden.

$client = new Interfax\Client([‘username’ => ‘…’, ‘password’ => ‘…’]);
$fax = $client->deliver([
    ‘faxNumber’ => ‘+492086090368’,
    ‘file’ => __DIR__ . ‘/../tests/Interfax/test.pdf’
]);

Als Parameter werden hier faxNumber: = die Faxnummer des Empfängers im internationalen Format und file: = der Pfad zur Datei, die gesendet werden soll.

In der deliver-Methode kann ein einzelnes Datei-Argument bereitgestellt werden oder über ein Array mehrere Datei-Werte.

Datei-Optionen:

  • Lokaler Pfad: Wenn die Datei größer als das erlaubte Limit ist, wird sie automatisch als Interfax\Document
  • URI: Eine URI von einem Interfax\Document.
  • Array: Ein Array, das eine gestreamte Ressource definiert.
  • Interfax\File: Ein Interfax\File Objekt.
  • Interfax\Document: Ein Interfax\Document
Senden eines Streams

Für Streams müssen bestimmte Parameter bereitgestellt werden.

$stream = fopen(‘/tmp/fax.pdf’, ‘rb’);
$fax = $client->deliver([
    ‘faxNumber’ => ‘+492086090368’,
    ‘file’ => [$stream, [‘name’ => ‘fax.pdf’, ‘mime_type’ => ‘application/pdf’]]
]);

  • Stream: Hier wird ein geöffnetes Stream-Handle erwartet (z.B. fopen).
  • Array: Ein Array, das den Namen und den MIME-Type der Datei enthält.

3. Funktionen für den Fax-Versand

Liste der ausgehenden Faxe abrufen

Diese Methode gibt eine Liste der zuletzt gesendeten Faxe zurück. Die Liste wird als Array gesendet und beinhaltet Interfax\Outbound\Fax Objekte.

$faxes = $client->outbound->recent();
// Rückgabe: Interfax\Outbound\Fax[]

Zusätzliche mögliche Parameter:

  • limit: Maximale Anzahl der zurückgegebenen Faxe.
  • lastId: Letzte Fax-ID, ab der die Liste abgerufen wird.
  • sortOrder: Sortierreihenfolge (asc oder desc).
  • userId: Filter nach Benutzer-ID.
Liste der abgeschlossenen Faxe abrufen

Diese Methode gibt eine Liste der Faxe zurück, die abgeschlossen sind und deren Ids im Array fax_ids angegeben wurden.

$fax_ids = [ … ]; // Array von Fax-IDs
$client->outbound->completed($fax_ids);
// Rückgabe: Interfax\Outbound\Fax[]

Informationen eines ausgehenden Faxes abrufen

Diese Methode gibt die Informationen zu einem gesendeten Fax zurück, einschließlich des aktuellen Status. Sollte das definierte Fax nicht gefunden werden wird NULL zurückgegeben.

$fax = $client->outbound->find(123456);
// Rückgabe: Interfax\Outbound\Fax || null

Bild eines ausgehenden Faxes abrufen

Diese Methode gibt das Bild des gesendeten Faxes zurück und speichert es an dem in ‚save()’ angegeben Pfad.

$fax = $client->outbound->find(123456);
if ($fax) {
    $image = $fax->image();
    $image->save(‘path/to/save/file/to.tif’);
}

Ausgehendes Fax stornieren

Solange das ausgehende Fax noch nicht versendet worden ist, kann es folgendermaßen storniert werden.

$fax = $client->outbound->find(123456);
if ($fax) {
    $fax->cancel();
}

Das Fax wird mithilfe der cancel-Methode über das Interfax\Outbound\Fax Modell storniert.

Faxliste durchsuchen

Über die Outbound-search-Methode kann die ausgehende Fax-Liste nach bestimmten Kriterien durchsucht werden. Zum Beispiel anhand der Fax-Nummer (faxNumber).

$faxes = $client->outbound->search([‘faxNumber’ => ‘+491230002305555’]);
// Rückgabe: Interfax\Outbound\Fax[]

Such-Optionen:

  • ids: Array von Fax-IDs.
  • reference: Referenznummer des Faxes.
  • dateFrom: Startdatum des Suchzeitraums.
  • dateTo: Enddatum des Suchzeitraums.
  • status: Status des Faxes.
  • userId: Benutzer-ID.
  • faxNumber: Faxnummer des Empfängers.
  • limit: Maximale Anzahl der zurückgegebenen Faxe.
  • offset: Startpunkt der Suche.
Ein Fax erneut versenden

Über folgende Methode kann das Fax an die ursprüngliche Nummer erneut gesandt werden:
$fax = $client->outbound->resend($id);
// Rückgabe: Interfax\Outbound\Fax gesendet an die ursprüngliche Nummer 

Über diese Methode kann das Fax an eine neue Nummer ($new_number) gesandt werden.
$fax = $client->outbound->resend($id, $new_number);
// Rückgabe: Interfax\Outbound\Fax gesendet an die neue Nummer

4. Funktionen für den Fax-Empfang

Liste der eingehenden Faxe abrufen

Mit folgender Methode wird eine Liste der eingehenden Faxe abgerufen.

$faxes = $inbound->incoming();
// Rückgabe: Interfax\Inbound\Fax[]

Diese Methode kann auch spezifisch nach ungelesenen Faxen gefiltert werden, indem der Wert „unreadOnly“ auf „true“ gesetzt wird.

$faxes = $inbound->incoming([‘unreadOnly’ => true]);
// Rückgabe: Interfax\Inbound\Fax[]

Vollständigen Datensatz eines eingehenden Faxes abrufen

Hierbei werden alle vorhandenen Metadaten eines eingehenden Faxes zurückgegeben wie z.B. die Empfangszeit, Absendernummer usw.. Sollte das Fax nicht gefunden werden wird NULL zurückgegeben.

$fax = $inbound->find(123456);
// Rückgabe: Interfax\Inbound\Fax || null

Bild eines eingehenden Faxes abrufen

Das Bild eines eingehendes Faxe kann mit folgender Methode abgerufen werden, wichtig ist die Angabe des zu speichernden Pfads „save()“.

$fax = $client->inbound->find(123456);
if ($fax) {
    $image = $fax->image();
    $image->save(‘path/to/save/file/to.pdf’);
}

Abrufen der Weiterleitungs-E-Mail

$fax = $client->inbound->find(123456);
if ($fax) {
    $emails = $fax->emails(); // Array-Struktur der Weiterleitungs-E-Mails
}

Die E-Mail-Adresse, an die das Fax weitergeleitet wurde, wird als Array zurück gegeben. In diesem Array befinden sich mehrere Informationen über den Versand der E-Mail wie z.B. der Versandzeitpunkt und der Status der E-Mail.

‚emailAdress‘ => ‚username@interfax.de‘,
‚messageStatus‘ => 0,
‚completionTime‘ => ‚2024-0623T17 => 24 => 11‘

Eingehendes Fax als gelesen/ungelesen markieren

$fax = $client->inbound->find(123456);
if ($fax) {
    $fax->markUnread(); // Rückgabe: true
    $fax->markRead(); // Rückgabe: true
}

Entsprechend der Auswahl wird das Fax als gelesen oder ungelesen markiert.

Eingehendes Fax erneut senden

Folgende Methode sendet ein eingehendes Fax erneut als E-Mail an die hinterlegte Empfänger Adresse.

$fax = $client->inbound->find(123456);
if ($fax) {
    $fax->resend();
}

5. Dokumentenverwaltung

Die Interfax\Document-Klasse ermöglicht das Hochladen größerer Dateien zum Faxen. Bsp.:

$document = $client->documents->create(‘test.pdf’, filesize(‘test.pdf’));
$stream = fopen(‘test.pdf’, ‘rb’);
$current = 0;
while (!feof($stream)) {
$chunk = fread($stream, 500);
            $end = $current + strlen($chunk);
            $doc->upload($current, $end-1, $chunk);
            $current = $end;
}
fclose($stream);



Neues Dokument für den Upload größerer Dateien erstellen

$params = […];

$document = $client->documents->create(‘test.pdf’, filesize(‘test.pdf’), $params);
// Rückgabe: Interfax\Document

Chunk in das angelegte Dokument hochladen

$document->upload($start, $end, $data); // Rückgabe: das Dokument-Objekt

Für den Upload eines Chunks ist der Start- und Endpunkt sowie die Angabe der Daten zwingend erforderlich. Schlägt die Verifizierung der Daten fehl so wird eine exception ausgegeben.

Eigenschaften eines neuen Dokuments für den Upload größerer Dateien abrufen

Mit dieser Methode werden die verschiedenen Eigenschaften des erstellten Dokuments abgerufen.

$status = $document->status;
$fileName = $document->fileName;
$attributes = $document->refresh()->attributes();
$location = $document->location;
$uri = $document→uri;

Erstelltes Dokument für den Upload größerer Dateien stornieren

Mit dieser Methode können Sie ein Dokument, das hochgeladen wird, stornieren. Das Dokument kann vor und nach der Fertigstellung storniert werden.

$document->cancel(); // Rückgabe: das Dokument-Objekt

6. Kontoabfrage

Das aktuelle Guthaben Ihres InterFAX-Kontos wird durch diesen Befehl erhalten Sie mit diesem Befehl:

echo $client->getBalance();
// Ausgabe: (string) 9.86

Das Faxguthaben wird als String zurückgegeben.

7. Hilfsklassen

Ausgehende Faxe

Die Interfax\Outbound\Fax-Klasse verpackt die Details eines gesendeten Faxes und kann über die meisten Outbound Methoden abgerufen werden.

$fax→refresh();
Aktualisiert die Daten des Fax-Objekts.

$fax→cancel();
Storniert das Fax.

$fax→hide();
Versteckt das Fax aus den Fax-Listen

$image = $fax→image();
Gibt das Bild des Faxes zurück.

 $new_fax = $fax→resend(‘+1111111’);
Sendet das Fax an eine neue Nummer.

$attributes = $fax→attributes();
Gibt ein Array der Fax-Eigenschaften zurück.

Eingehende Faxe

Die Interfax\Inbound\Fax-Klasse verpackt die Details eines eingehenden Faxes und kann über die meisten Inbound Methoden abgerufen werden.

$fax→refresh();
Aktualisiert die Eigenschaften des Faxes.

 $fax→markRead();
Markiert das Fax als gelesen.

 $fax→markUnread();
Markiert das Fax als ungelesen

$fax→resend();
Sendet das Fax erneut an die Weiterleitungs-E-Mail Adresse.

 $image = $fax→image();
Gibt das Bild des Faxes zurück.

$email_array = $fax→emails();
Gibt die Weiterleitungs-E-Mail zurück.

$attributes = $fax→attributes();
Gibt ein Array der Fax-Eigenschaften zurück. 

8. Query-Parameter

Wenn die verwendeten Methoden eine Hash-Array-Struktur von Abfrageparametern unterstützen, werden diese wie angegeben an den API-Endpunkt weitergeleitet.
Dadurch wird sichergestellt, dass alle künftigen Parameter, die möglicherweise hinzugefügt werden, von der APO unverändert unterstützt werden.

Die einzigen Werte, die bearbeitet werden, sind Boolesche Werte, die in den Text „TRUE“ bzw. „FALSE“ übersetzt werden.

9. Exceptions

Jeder Methodenaufruf, der einen Aufruf der Interfax RESTful API beinhaltet, kann eine Instanz von Interfax\Exception\RequestException auslösen.

Eine Exception wird für alle Anfragen ausgelöst, die keinen erfolgreichen HTTP-Statuscode zurückgeben. Das Ziel dieser Exception ist es, Informationen, die möglicherweise zurückgegeben werden, einfach zu verpacken und darzustellen.

Bestimmte Antworten der API enthalten weitere Details, die in diesem Fall an die Meldung der Exception angehängt werden.

try {
    $interfax->deliver(…);
} catch (Interfax\Exception\RequestException $e) {
    echo $e->getMessage();
    echo $e->getStatusCode();
    throw $e->getWrappedException();
}

10. Beispiele für eine PHP-Programmierung

Hier finden Sie Beispiele für die Programmierung einer einfachen Anwendung:

Beispiel PHP Fax-Versand
Beispiel PHP Abruf Fax-Informationen
Beispiel PHP Abruf Details (Kontodetails und Versandliste)

Testen Sie selbst
(Browsersprache muss Englisch sein)

Kostenlosen Developer-Account anfordern