Handhabung

Um die Funktionalität des OMC-Connectors nutzen zu können, muss dieser in Ihr PHP-Skript eingebunden werden:

require_once 'omc_connector/OMC_Connector.php';

Der OMC Connector deckt alle Anwendungsfälle von der Abfrage und Erzeugung von Daten (wie Kontaktpersonen) bis zur Änderung von Feldern (Attributen) ab. Die Daten im OMC sind im OMC Connector durch Klassen repräsentiert. So steht beispielsweise über die Klasse OMC_Account eine Methode zur Verfügung, mit der ein Account aus dem OMC in eine Instanzvariable geladen werden kann.

Daten vom OMC auslesen

Um Daten vom OMC auszulesen, verwenden Sie bitte die dem Typ der Daten entsprechenden Klassenmethoden des OMC Connectors – für Personen also Methoden der Klasse OMC_Contact, für Mailings die Methoden von OMC_Mailing usw. Die meisten Klassen verfügen über die Methode find(id), die eine Instanz der über die id identifizierte Entität im OMC liefert. Beispiel:

$contact = OMC_Contact::find(3);

Nach dieser Operation können Sie über die Instanzvariable $contact auf die Attribute der Entität zugreifen. Alle diese Attribute können Sie gezielt einzeln abrufen:

$vorname_des_contacts = $contact->first_name;
$nachname_des_contacts = $contact->last_name;

Es ist auch möglich, alle Attribute als Hash-Array auszulesen. Verwenden Sie hierfür die Methode getFields():

$werte_des_contacts = $contact->getFields();

OMC-Daten ändern und speichern

Um Daten, die vom OMC ausgelesen wurden, zu ändern, können Sie die zur Verfügung gestellten Instanzmethoden nutzen. Um einzelne Werte zu ändern, können Sie wieder direkt auf diese zugreifen, d.h. die Attribute der Instanz ansprechen. Beispiel:

$contact->first_name = "Anderer Vorname";
$contact->last_name = "Neuer Nachname";

Diese Anweisungen ändern nur die Instanz in Ihrem Skript, nicht jedoch die entsprechende Entität im OMC. Um die Entität zu ändern, muss die Instanzmethode save() aufgerufen werden:

$contact->save();

Auch bei Hash-Arrays, die die zu ändernden Schlüssel/Wert-Paare enthalten, gibt es zwei Möglichkeiten der Speicherung:

  1. Änderungen nur lokal in der Instanz durchführen
    Die Änderungen sind erst nach dem Aufruf von save() im OMC verfügbar. Beispiel:

    $array_mit_aenderungen = array("first_name" => "Anderer Vorname", 
      "last_name" => "Neuer Nachname");
    $contact->updateFields($array_mit_aenderungen);
    $contact->save();
    
  2. Änderungen sowohl lokal als auch an der OMC-Entität durchführen
    Hierbei werden die Änderungen sofort an das OMC weitergegeben. Beispiel:

    $array_mit_aenderungen = array("first_name" => "Anderer Vorname", 
      "last_name" => "Neuer Nachname");
    $contact->updateAttributes($array_mit_aenderungen);
    

Exceptions

Wann immer eine direkte Kommunikation mit dem OMC stattfindet (etwa bei find(id) oder save()), kann es zu Exceptions kommen. Eine Exception tritt beispielsweise auf, wenn das OMC nicht verfügbar ist, der OMC Connector falsch konfiguriert ist oder auf eine Ressource zugegriffen wird, die nicht existiert. Die Exception gibt Ihnen die Möglichkeit, auf eine solche "Ausnahmesituation" zu reagieren, indem Sie diese "abfangen" und mit geeignetem Code behandeln.

Jede Exception, die der OMC Connector auslösen kann, ist eine Unterklasse von OMC_Exception. Beispiel:

try {
  $contact = OMC_Contact::find(999999);
} catch (OMC_ResourceNotFoundException $e) {
  // Spezielle Exception
  echo "Im OMC gibt es keine Person mit der ID 999999.";
} catch (OMC_Exception $e) {
  // Allgemeine Exception
  echo "Ein anderer Fehler ist aufgetreten.";
}

Wenn Daten, die bereits vom OMC geladen wurden, nur ausgelesen werden (wie $contact->first_name), können keine Exceptions des OMC Connectors auftreten.