<?php
/**
* EmailGarage class
*
* This source file can be used to communicate with EmailGarage (http://www.emailgarage.com/)
*
* The class is documented in the file itself.
* If you find any bugs help me out and report them. Reporting can be done by sending an email to emailgarage[at]verkoyen[dot]eu.
* If you report a bug, make sure you give me enough information (include your code).
*
* Remark
* Not all methods are implemented, in this project I only needed some of them.
*
* Changelog since 1.0.0
* - profileAdd & profilesUpdate are changed so you can specify each parameter for each field yourself
*
* License
* Copyright (c) 2008, Tijs Verkoyen. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* - Neither the name of Tijs Verkoyen, EmailGarage nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
*
* This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed.
* In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
*
* @author Tijs Verkoyen <hide@address.com>
* @version 1.0.1
*
* @copyright Copyright (c) 2008, Tijs Verkoyen. All rights reserved.
* @license BSD License
*/
class EmailGarage
{
/**
* The companyId (generated by EMG themself)
*
* @var string
*/
private $companyId;
/**
* The EMG-password
*
* @var string
*/
private $password;
/**
* The EMG-user
*
* @var string
*/
private $userId;
/**
* Default constructor
*
* @return void
* @param string $userId
* @param string $password
* @param string $companyId
*/
public function __construct($userId, $password, $companyId)
{
// set properties
$this->userId = (string) $userId;
$this->password = (string) $password;
$this->companyId =(string) $companyId;
}
/**
* Make the actual call
*
* @return mixed
* @param string $function
* @param array $aParameters
*/
private function doCall($function, $aParameters)
{
// sleep (so we don't overload the servers)
usleep(2000);
// recreate parameters
$aRealParameters['userId'] = (string) $this->userId;
$aRealParameters['password'] = (string) $this->password;
$aRealParameters['companyId'] = (string) $this->companyId;
// add passed parameters
foreach ($aParameters as $key => $value) $aRealParameters[$key] = $value;
// soap options
$aSoapOptions = array('soap_version' => SOAP_1_1,
'connection_timeout' => 120,
'trace' => true);
// catch exceptions
try
{
// create client
$soapClient = new SoapClient('https://connect.emailgarage.com/WebServices/WebService.asmx?WSDL', $aSoapOptions);
// do call
$response = $soapClient->__soapCall($function, array($aRealParameters));
// build var name
$name = $function .'Result';
// return response
if(isset($response->$name)) return $response->$name;
// no data, but a response
elseif (is_object($response)) return true;
// no idea
else return false;
}
// catch as SoapFault
catch (SoapFault $fault)
{
// get error message
if(isset($fault->detail->exception)) $message = (string) $fault->detail->exception;
elseif(isset($fault->detail->error)) $message = (string) $fault->detail->error;
else $message = $fault->getMessage();
// throw error
throw new Exception($message);
}
}
/**
* Create an email
*
* @return string
* @param string $campaignId
* @param string $name
* @param string $subject
* @param string $messagePlain
* @param string $messageHtml
* @param string $optionPriority
* @param string $originalTemplate
* @param string $fromEmail
* @param string $fromName
* @param string $emailEncoding
* @param string $replyAddress
* @param string $mtaAddress
* @param string $trackingUrl
* @param bool $textTracking
* @param string $country
* @param string $culture
*/
public function emailCreate($campaignId, $name, $subject, $messagePlain, $messageHtml, $optionPriority, $originalTemplate, $fromEmail, $fromName, $emailEncoding, $replyAddress, $mtaAddress, $trackingUrl, $textTracking, $country, $culture)
{
// build parameters
$aParameters['campaignId'] = (string) $campaignId;
$aParameters['name'] = (string) $name;
$aParameters['subject'] = (string) $subject;
$aParameters['messageText'] = (string) $messagePlain;
$aParameters['messageHtml'] = (string) $messageHtml;
$aParameters['optionPriority'] = (string) $optionPriority;
$aParameters['originalTemplate'] = (string) $originalTemplate;
$aParameters['fromEmail'] = (string) $fromEmail;
$aParameters['fromName'] = (string) $fromName;
$aParameters['emailEncoding'] = (string) $emailEncoding;
$aParameters['replyAddress'] = (string) $replyAddress;
$aParameters['mtaAddress'] = (string) $mtaAddress;
$aParameters['trackingUrl'] = (string) $trackingUrl;
$aParameters['textTracking'] = (bool) $textTracking;
$aParameters['country'] = (string) $country;
$aParameters['culture'] = (string) $culture;
return $this->doCall('CreateEmail', $aParameters);
}
/**
* Get all fields
*
* @return array
*/
public function fieldsGetAll()
{
// init vars
$aFields = array();
// get response
$response = $this->doCall('GetProfileFields', array());
// loop fields
foreach((array) $response->ProfileField as $row)
{
$row = (array) $row;
// cleanup vars
$name = utf8_decode((string) $row['Name']);
$type = utf8_decode((string) $row['Type']);
$id = utf8_decode((string) $row['Id']);
$isCustom = (bool) $row['IsCustom'];
// add to fields
$aFields[$name] = array('id' => $id, 'type' => $type, 'is_custom' => $isCustom);
}
return $aFields;
}
/**
* Create a flow
*
* @return string
* @param string $campaignId
* @param string $emailId
* @param string $eql
* @param bool $excludeRobinson
* @param bool $excludeBlacklist
*/
public function flowCreate($campaignId, $emailId, $eql, $excludeRobinson = true, $excludeBlacklist = true)
{
// build parameters
$aParameters['campaignId'] = $campaignId;
$aParameters['postingId'] = $emailId;
$aParameters['eql'] = $eql;
$aParameters['excludeRobinson'] = (bool) $excludeRobinson;
$aParameters['excludeBlacklist'] = (bool) $excludeBlacklist;
return $this->doCall('CreateFlow', $aParameters);
}
/**
* Starts a certain flow
*
* @return unknown
* @param string $flowId
* @param bool[optional] $restart
*/
public function flowStartById($flowId, $restart = false)
{
$aParameters['flowId'] = (string) $flowId;
$aParameters['restart'] = (bool) $restart;
return $this->doCall('StartFlowById', $aParameters);
}
/**
* Add a label and returns the id
* if the label already exists the id will be returned
*
* @return string
* @param string $name
* @param string[optional] $isProfileLabel
* @param string[optional] $isAssetLabel
* @param string[optional] $isCampaignLabel
*/
public function labelAdd($name, $isProfileLabel = true, $isAssetLabel = true, $isCampaignLabel = true)
{
// build parameters
$aParameters['labelName'] = (string) $name;
$aParameters['isProfileLabel'] = (bool) $isProfileLabel;
$aParameters['isAssetLabel'] = (bool) $isAssetLabel;
$aParameters['isCampaignLabel'] = (bool) $isCampaignLabel;
// do the call
try
{
return (string) $this->doCall('CreateLabel', $aParameters);
}
// something went wrong?
catch (Exception $e)
{
// no label found
if($e->getMessage() == 'A label with this name already exists.')
{
// get the label id
$return = $this->labelGetIdByName($name);
// validate
if($return === false) throw new Exception('The label ('. $name .') exists, but there is no id.');
// return
return $return;
}
// throw exception up
else throw $e;
}
}
/**
* Updates a label
*
* @return bool
* @param string $labelId
* @param string $newLabelName
* @param string[optional] $isProfileLabel
* @param string[optional] $isAssetLabel
* @param string[optional] $isCampaignLabel
*/
public function labelEdit($labelId, $newLabelName, $isProfileLabel = true, $isAssetLabel = true, $isCampaignLabel = true)
{
// build parameters
$aParameters['labelId'] = (string) $labelId;
$aParameters['newLabelName'] = (string) $newLabelName;
$aParameters['isProfileLabel'] = (bool) $isProfileLabel;
$aParameters['isAssetLabel'] = (bool) $isAssetLabel;
$aParameters['isCampaignLabel'] = (bool) $isCampaignLabel;
return (bool) $this->doCall('EditLabel', $aParameters);
}
/**
* Get all labels
*
* @return array
*/
public function labelGetAll()
{
// get response
$response = $this->doCall('GetAllLabels', array());
// replace stuff
$xmlString = str_replace(array('diffgr:', 'msdata:'), array('diffgr_', 'msdata_'), $response->any);
// init vars
$aLabels = array();
// get labels
$aMatches = array();
preg_match_all('|<Labels(.*)</Labels>|U', $xmlString, $aMatches);
// loop matches
if(isset($aMatches[0]))
{
foreach ($aMatches[0] as $row)
{
$xml = simplexml_load_string($row);
if($xml !== false && isset($xml->Name) && isset($xml->LabelID))
{
$aTemp['name'] = utf8_decode((string) $xml->Name);
$aTemp['label_id'] = utf8_decode((string) $xml->LabelID);
$aTemp['category_id'] = utf8_decode((string) $xml->CategoryId);
$profileEnabled = utf8_decode((string) $xml->CategoryId);
$campaignEnabled = utf8_decode((string) $xml->CategoryId);
$assetEnabled = utf8_decode((string) $xml->CategoryId);
$postingEnabled = utf8_decode((string) $xml->CategoryId);
$aTemp['profile_enabled'] = (bool) ($profileEnabled == 'true');
$aTemp['campaign_enabled'] = (bool) ($campaignEnabled == 'true');
$aTemp['asset_enabled'] = (bool) ($assetEnabled == 'true');
$aTemp['posting_enabled'] = (bool) ($postingEnabled == 'true');
$aTemp['source'] = utf8_decode((string) $xml->Source);
$aTemp['created_by'] = utf8_decode((string) $xml->CreatedBy);
$aTemp['create_time'] = (int) strtotime(utf8_decode((string) $xml->CreatedDateTime));
$aTemp['modified_by'] = utf8_decode((string) $xml->ModifiedBy);
$aTemp['modify_time'] = (int) strtotime(utf8_decode((string) $xml->ModifiedDateTime));
$aTemp['version'] = utf8_decode((string) $xml->Version);
// add to labels
$aLabels[$aTemp['label_id']] = $aTemp;
}
}
}
return $aLabels;
}
/**
* Retrieves the id of a label by its name. The function
* will return false it the label doesn't exists.
*
* @return mixed
* @param string $name
*/
public function labelGetIdByName($name)
{
// build parameters
$aParameters['labelName'] = (string) $name;
// do the call
try
{
return (string) $this->doCall('GetLabelIdByName', $aParameters);
}
// something went wrong?
catch (Exception $e)
{
// no label found
if($e->getMessage() == 'Label does not exist for this company') return false;
// throw exception up
else throw $e;
}
}
/**
* Removes a label
*
* @return bool
* @param string $labelId
*/
public function labelRemove($labelId)
{
// build parameters
$aParameters['labelId'] = (string) $labelId;
return (bool) $this->doCall('RemoveLabel', $aParameters);
}
/**
* Adds a new profile
*
* @return string
* @param array $aFields
*/
public function profileAdd($aFields)
{
// build parameters
$aParameters['profileFields'] = array();
// add fields
foreach ($aFields as $value) $aParameters['profileFields'][] = $value;
return (string) $this->doCall('AddProfile', $aParameters);
}
/**
* Assigns a label to a profile
*
* @return bool
* @param string $labelId
* @param string $profileId
*/
public function profileAssignLabel($labelId, $profileId)
{
// build parameters
$aParameters['labelId'] = (string) $labelId;
$aParameters['profileId'] = (string) $profileId;
return (bool) $this->doCall('AssignLabelToProfile', $aParameters);
}
/**
* Assign labels to a profile
*
* @return bool
* @param string $labelNames .. twas te moeilijk om consistent te zijn...
* @param string $email .. idem
* */
public function profileAssignLabels($labelNames, $email)
{
// build parameters
$aParameters['eql'] = '(((Field("Email") = "'. $email .'")));' ;
$aParameters['labelsList'] = implode(',', $labelNames);
$aParameters['separator'] = ',';
return $this->doCall('AddLabelsToProfilesList', $aParameters);
}
/**
* Removes existing labels from profiles retrieved from eql
*
* @return void
* @param array $labelNames .. twas te moeilijk om consistent te zijn...
* @param string $eql
*/
public function profileRemoveLabels($labelNames, $eql)
{
// build parameters
$aParameters['eql'] = (string) $eql ;
$aParameters['labelsList'] = implode(',', $labelNames);
return $this->doCall('RemoveLabelsFromProfilesList', $aParameters);
}
/**
* Get all data for a profile
*
* @return array
* @param string $profileId
*/
public function profileGetById($profileId)
{
// build parameters
$aParameters['profileId'] = (string) $profileId;
// get response
$response = $this->doCall('GetProfileById', $aParameters);
// init var
$aReturn = array();
// values?
if(isset($response->ProfileField))
{
// redefine as array
$fields = (array) $response->ProfileField;
// loop fields
foreach ($fields as $field)
{
// get key and value
if(isset($field->Name)) $key = (string) $field->Name;
if(isset($field->Value)) $value = $field->Value;
else $value = null;
// reformat value
switch (strtolower($value))
{
case 'false':
$value = false;
break;
case 'true':
$value = true;
break;
}
// add to return
if(isset($key, $value)) $aReturn[$key] = $value;
}
}
// return
return $aReturn;
}
/**
* Get all profile-ids by email
*
* @return mixed
* @param string $email
*/
public function profileGetIdsByEmail($email)
{
// build parameters
$aParameters['emailAddress'] = (string) $email;
// get answer
$response = $this->doCall('GetProfileIdsByEmail', $aParameters);
// are there ids's?
if(isset($response->guid)) return (array) $response->guid;
// fallback
return false;
}
/**
* Get all profileIds with a certain labelId
*
* @return mixed
* @param string $labelId
*/
public function profileGetIdsByLabelId($labelId)
{
// build parameters
$aParameters['labelId'] = (string) $labelId;
// get answer
$response = $this->doCall('GetProfileIdsByLabelId', $aParameters);
// are there ids's?
if(isset($response->guid)) return (array) $response->guid;
// fallback
return false;
}
/**
* Removes a profile by its id
*
* @return bool
* @param string $profileId
*/
public function profileRemove($profileId)
{
// build parameters
$aParameters['profileId'] = (string) $profileId;
return (bool) $this->doCall('RemoveProfileById', $aParameters);
}
/**
* Removes a label that was assigned to a profile
*
* @return bool
* @param string $labelId
* @param string $profileId
*/
public function profileRemoveLabel($labelId, $profileId)
{
// build parameters
$aParameters['labelId'] = (string) $labelId;
$aParameters['profileId'] = (string) $profileId;
return (bool) $this->doCall('RemoveLabelFromProfile', $aParameters);
}
/**
* Updates a profile by its id
*
* @return string
* @param string $profileId
* @param array $aFields
*/
public function profileUpdate($profileId, $aFields)
{
// build parameters
$aParameters['profileId'] = (string) $profileId;
$aParameters['profileFields'] = array();
// add fields
foreach ($aFields as $value) $aParameters['profileFields'][] = $value;
// get the answer
return (bool) $this->doCall('UpdateProfileById', $aParameters);
}
}
?>