Handling

To enanble the functions of the OMC Connector, it needs to be integrated into your PHP script:

require_once 'omc_connector/OMC_Connector.php';

The OMC Connector covers all application areas, ranging from data query and creation to the modification of fields (attributes). In the OMC Connector, the data stored in the OMC become accessible through classes that represent the data. The OMC_Account class, for example, provides a method that fetches the data of an account from the OMC and stores it in an instance variable.

Fetching Data from the OMC

To fetch data from the OMC, please use the OMC Connector's class methods that match the type of the data to be retrieved, i.e. methods of the OMC_Contact class for contact person data, OMC_Mailing class methods for for mailing data, and so on. Most classes provide a method named find(id) that returns an instance of the OMC entity identified by means of its id. An example:

$contact = OMC_Contact::find(3);

After this operation, you can access the attributes of the entity via the $contact instance variable. All attributes can be read out individually:

$first_name_of_contact = $contact->first_name;
$last_name_of_contact = $contact->last_name;

You can also read out all attributes as a hash array. Use the getFields() method for this:

$all_contact_values = $contact->getFields();

Changing and Storing OMC Data

To modify the data retrieved from the OMC, the instance methods provided can be used. Individual values can be changed directly by writing to the attributes of the instance. Example:

$contact->first_name = "Other First Name";
$contact->last_name = "New First Name";

These instructions only modify the instance of your script, not the corresponding entity in the OMC. To modify the entity, call the save() instance method:

$contact->save();

Also for hash arrays containing the key/value pairs to be modified, two ways for storing them exist:

  1. Changing data only locally in the instance
    The modifications are only made in the OMC after save() has been called. Example:

    $array_of_changes = array("first_name" => "Other First Name", 
      "last_name" => "New Last Name");
    $contact->updateFields($array_of_changes);
    $contact->save();
    
  2. Changing the instance as well as the OMC entity
    This will cause the changes to be immediately passed to the OMC. Example:

    $array_of_changes = array("first_name" => "Other First Name", 
      "last_name" => "New Last Name");
    $contact->updateAttributes($array_of_changes);
    

Exceptions

Whenever the OMC Connector directly communicates with the OMC (e.g. when find(id) or save() are called), exceptions may be risen. An exception occurs, for instance, if the OMC cannot be reached, the OMC Connector has been misconfigured, or a nonexisting resource is addressed. The exception makes it possible to react to such a special situation by catching it and providing the code required to handle it.

Every exception the OMC Connector is able to rise is a subclass of OMC_Exception. An example may illustrate this:

try {
  $contact = OMC_Contact::find(999999);
} catch (OMC_ResourceNotFoundException $e) {
  // Special exception
  echo "No person with the ID 999999 exists in the OMC.";
} catch (OMC_Exception $e) {
  // General exception
  echo "A different error has occurred.";
}

If data that have already been fetched from the OMC are only read out (like $contact->first_name, for example), no exceptions originating from the OMC Connector can arise.