diff --git a/README.md b/README.md index 6d9dede..c1e4c2e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,23 @@ -esp-api-engine -============== +# Crazy Awesome ESP E-Ngine API Client -E-Ngine ESP Api +Connect to the E-Ngine ESP with the API Client. + +## Information ## + - [E-Ngine ESP](http://www.e-ngine.nl/) + +## Installation ## +Preferred way of installing is though [Composer](http://getcomposer.org). Add the following line to you `require` + + "cac/esp-api-engine": ">=v0.1" + +## API Configuration ## +The Adapter uses the E-Ngine SOAP Webservice for communication. When creating the `EngineApi` class some configuration is needed + + + `domain` - The domain where E-Ngine is availabe. (e.g. `newsletter.yourdomain.com`) + + `path` - Path to the SOAP entry point on the `domain`. (e.g. `/soap/server.live.php`) + + `customer` - Your E-Ngine customer name + + `user` - Your E-Ngine user name + + `password` - Your E-Ngine password + +## Todo ## +The API Client doesn't have all calls implemented at the moment. To use the latest version download the development version. diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..cdf4ed9 --- /dev/null +++ b/composer.json @@ -0,0 +1,31 @@ +{ + "name": "cac/esp-api-engine", + "description": "Crazy Awesome E-Ngine API Client", + "keywords": ["Email Service Provider", "esp", "email", "e-ngine"], + "homepage": "http://www.crazyawesomecompany.com", + "license": "BSD-3-Clause", + "support": { + "issues": "https://github.com/CrazyAwesomeCompany/esp-api-engine/issues", + "source": "https://github.com/CrazyAwesomeCompany/esp-api-engine" + }, + "autoload": { + "psr-0": { + "\\CAC\\Component\\ESP\\Api\\Engine": "lib/" + }, + "classmap": [ "lib/" ] + }, + "require": { + "psr/log": ">=1" + }, + "suggest": { + "monolog/monolog": "Adds logging abilities" + }, + "authors": [ + { + "name": "Nick de Groot", + "email": "nick@crazyawesomecompany.com", + "homepage": "http://www.crazyawesomecompany.com", + "role": "Developer" + } + ] +} diff --git a/lib/CAC/Component/ESP/Api/Engine/EngineApi.php b/lib/CAC/Component/ESP/Api/Engine/EngineApi.php new file mode 100644 index 0000000..a0e7487 --- /dev/null +++ b/lib/CAC/Component/ESP/Api/Engine/EngineApi.php @@ -0,0 +1,352 @@ + + * + * @todo Implement `Mailinglist_getUnsubscriptionsAsCSV` + * @todo Implement `Subscriber_getByUniqueID` + * @todo Implement `Subscriber_sendMailingToSubscribers` + * + */ +class EngineApi implements LoggerAwareInterface +{ + /** + * Api connection + * + * @var \SoapClient + */ + private $connection; + + /** + * @var LoggerInterface + */ + private $logger; + + /** + * Api configuration + * + * @var array + */ + private $config; + + public function __construct(array $config) + { + $this->config = array_replace_recursive( + array( + "domain" => "", + "path" => "/soap/server.live.php", + "customer" => "", + "user" => "", + "password" => "", + "trace" => false + ), + $config + ); + } + + /** + * Create a new E-Ngine Mailing from content + * + * @param string $htmlContent + * @param string $textContent + * @param string $subject + * @param string $fromName + * @param string $fromEmail + * @param string $replyTo + * + * @return integer + * + * @throws EngineApiException + */ + public function createMailingFromContent($htmlContent, $textContent, $subject, $fromName, $fromEmail, $replyTo = null, $title = null) + { + if (null === $replyTo) { + $replyTo = $fromEmail; + } + + if (null === $title) { + $title = $subject; + } + + $mailingId = $this->performRequest( + 'Mailing_createFromContent', + utf8_encode($htmlContent), + utf8_encode($textContent), + utf8_encode($title), + utf8_encode($subject), + $fromName, + $fromEmail, + $replyTo + ); + + if (!is_numeric($mailingId)) { + $e = new EngineApiException(sprintf('Could not create mailing from content. Engine Result: [%s]', $mailingId)); + $e->setEngineCode($mailingId); + + throw $e; + } + + return $mailingId; + } + + /** + * Create a new mailing based on an E-Ngine Template + * + * @param integer $templateId + * @param string $subject + * @param string $fromName + * @param string $fromEmail + * @param string $replyTo + * @param string $title + * + * @return integer + * + * @throws EngineApiException + */ + public function createMailingFromTemplate($templateId, $subject, $fromName, $fromEmail, $replyTo = null, $title = null) + { + if (null === $replyTo) { + $replyTo = $fromEmail; + } + + if (null === $title) { + $title = $subject; + } + + $mailingId = $this->performRequest( + 'Mailing_createFromTemplate', + $templateId, + utf8_encode($title), + utf8_encode($subject), + $fromName, + $fromEmail, + $replyTo + ); + + if (!is_numeric($mailingId)) { + $e = new EngineApiException(sprintf('Could not create mailing from template. Engine Result: [%s]', $mailingId)); + $e->setEngineCode($mailingId); + + throw $e; + } + + return $mailingId; + } + + public function sendMailing($mailingId, array $users, $date = null, $mailinglistId = null) + { + if (null === $date) { + $date = date("Y-m-d H:i:s"); + } + + // Check if users are set + if (empty($users)) { + throw new EngineApiException("No users to send mailing"); + } + + $result = $this->performRequest( + 'Subscriber_sendMailingToSubscribers', + $mailingId, + $date, + $users, + $mailinglistId + ); + + if (!is_numeric($result)) { + $e = new EngineApiException(sprintf('Could not send mailing [%d]. Engine Result: [%s]', $mailingId, $result)); + $e->setEngineCode($result); + + throw $e; + } + + return $result; + } + + /** + * Subscribe a User to a Mailinglist + * + * @param array $user The user data + * @param integer $mailinglistId The mailinglist id to subscribe the user + * @param bool $confirmed Is the user already confirmed + * + * @return string + * + * @throws EngineApiException + */ + public function subscribeUser(array $user, $mailinglistId, $confirmed = false) + { + $result = $this->performRequest('Subscriber_set', $user, !$confirmed, $mailinglistId); + + if (!in_array($result, array('OK_UPDATED', 'OK_CONFIRM', 'OK_BEDANKT'))) { + $e = new EngineApiException(sprintf('User not subscribed to mailinglist. Engine Result: [%s]', $result)); + $e->setEngineCode($result); + + throw $e; + } + + return $result; + } + + /** + * Unsubscribe a User from a Mailinglist + * + * @param string $email The emailaddress to unsubscribe + * @param integer $mailinglistId The mailinglist id to unsubscribe the user from + * @param bool $confirmed Is the unsubscription already confirmed + * + * @return string + * + * @throws EngineApiException + */ + public function unsubscribeUser($email, $mailinglistId, $confirmed = false) + { + $result = $this->performRequest('Subscriber_unsubscribe', $email, !$confirmed, $mailinglistId); + + if (!in_array($result, array('OK', 'OK_CONFIRM'))) { + $e = new EngineApiException(sprintf('User not unsubscribed from mailinglist. Engine Result: [%s]', $result)); + $e->setEngineCode($result); + + throw $e; + } + + return $result; + } + + /** + * Get all mailinglists of the account + * + * @return array + */ + public function getMailinglists() + { + $result = $this->performRequest('Mailinglist_all'); + + return $result; + } + + /** + * Get all unsubscriptions from a mailingslist of a specific time period + * + * @param integer $mailinglistId + * @param \DateTime $from + * @param \DateTime $till + * + * @return array + */ + public function getMailinglistUnsubscriptions($mailinglistId, \DateTime $from, \DateTime $till = null) + { + if (null === $till) { + // till now if no till is given + $till = new \DateTime(); + } + + $result = $this->performRequest( + 'Mailinglist_getUnsubscriptions', + $from->format('Y-m-d H:i:s'), + $till->format('Y-m-d H:i:s'), + null, + array('self', 'admin', 'hard', 'soft', 'spam', 'zombie'), + $mailinglistId + ); + + return $result; + } + + /** + * Get Mailinglist Subscriber information + * + * @param integer $mailinglistId + * @param string $email + * + * @return array + */ + public function getMailinglistUser($mailinglistId, $email) + { + $result = $this->performRequest( + 'Subscriber_getByEmail', + $email, + array('email', 'firstname', 'infix', 'lastname'), + $mailinglistId + ); + + return $result; + } + + /** + * Perform the SOAP request against the E-Ngine webservice + * + * @param string $method The method to call + * @param mixed ... Additional parameters + * + * @return mixed + * + * @throws EngineApiException Converted SoapFault Exception + */ + protected function performRequest($method) { + // Perform the SOAP request + $args = func_get_args(); + // remove method argument + array_shift($args); + + try { + if ($this->logger) { + $this->logger->debug(sprintf("E-Ngine API call: %s -> %s", $method, json_encode($args))); + } + + $result = call_user_func_array(array($this->getConnection(), $method), $args); + } catch (\SoapFault $e) { + if ($this->logger) { + $this->logger->error(sprintf("E-Ngine API error: %s", $e->getMessage())); + } + // Convert to EngineApiException + throw new EngineApiException($e->getMessage(), $e->getCode(), $e->getPrevious()); + } + + return $result; + } + + /** + * Get the SOAP connection + * + * @return SoapClient The SoapClient connection + */ + protected function getConnection() + { + if ($this->connection === null) { + // create a connection + $connection = new \SoapClient( + null, + array( + "location" => "http://" . $this->config["domain"] . $this->config["path"], + "uri" => "http://" . $this->config["domain"] . $this->config["path"], + "login" => $this->config["customer"] . "__" . $this->config["user"], + "password" => $this->config["password"], + "trace" => $this->config["trace"] + ) + ); + + $this->connection = $connection; + } + + return $this->connection; + } + + /** + * Set the logger + * + * @param LoggerInterface $logger + */ + public function setLogger(LoggerInterface $logger) + { + $this->logger = $logger; + } +} diff --git a/lib/CAC/Component/ESP/Api/Engine/EngineApiException.php b/lib/CAC/Component/ESP/Api/Engine/EngineApiException.php new file mode 100644 index 0000000..1c81c9e --- /dev/null +++ b/lib/CAC/Component/ESP/Api/Engine/EngineApiException.php @@ -0,0 +1,13 @@ +engineCode = $code; + } +}