diff --git a/README.md b/README.md index e206a689..e8731e39 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,56 @@ $resultDelete = $mgClient->httpClient()->httpDelete($path, $params); ``` + +### SubAccounts + +```php +//Enable Sub Account +try { + $items = $mgClient->subaccounts()->enable($id); +} catch (Exception $exception) { + echo sprintf('HTTP CODE - %s,', $exception->getCode()); + echo sprintf('Error - %s', $exception->getMessage()); +} + +//Create a new Sub Account +try { + $items = $mgClient->subaccounts()->create('some name'); +} catch (Exception $exception) { + echo sprintf('HTTP CODE - %s,', $exception->getCode()); + echo sprintf('Error - %s', $exception->getMessage()); +} + +//Get All +try { + $items = $mgClient->subaccounts()->index(); + + print_r($items->getItems()); +} catch (Exception $exception) { + echo sprintf('HTTP CODE - %s,', $exception->getCode()); + echo sprintf('Error - %s', $exception->getMessage()); +} +``` +### Performing API Requests "On Behalf Of" Subaccounts +More Detailed you can read here - [https://help.mailgun.com/hc/en-us/articles/16380043681435-Subaccounts#01H2VMHAW8CN4A7WXM6ZFNSH4R](https://help.mailgun.com/hc/en-us/articles/16380043681435-Subaccounts#01H2VMHAW8CN4A7WXM6ZFNSH4R) +```php +$mgClient = Mailgun::create( + 'xxx', + 'yyy', + $subAccountId +); +``` + +```php +use Mailgun\HttpClient\HttpClientConfigurator; +use Mailgun\Hydrator\NoopHydrator; + +$configurator = new HttpClientConfigurator(); +$configurator->setEndpoint('http://bin.mailgun.net/aecf68de'); +$configurator->setApiKey('key-example'); +$configurator->setSubAccountId($subAccountId) +``` + ### All usage examples You will find more detailed documentation at [/doc](doc/index.md) and on diff --git a/src/Api/Attachment.php b/src/Api/Attachment.php index 49e7c6ab..84dca827 100644 --- a/src/Api/Attachment.php +++ b/src/Api/Attachment.php @@ -12,6 +12,7 @@ namespace Mailgun\Api; use Mailgun\Assert; +use Mailgun\Exception\UnknownErrorException; use Psr\Http\Client\ClientExceptionInterface; use Psr\Http\Message\ResponseInterface; @@ -22,16 +23,18 @@ class Attachment extends HttpApi { /** * @param string $url + * @param array $requestHeaders * @return ResponseInterface * @throws ClientExceptionInterface + * @throws UnknownErrorException */ - public function show(string $url): ResponseInterface + public function show(string $url, array $requestHeaders = []): ResponseInterface { Assert::stringNotEmpty($url); Assert::regex($url, '@https://.*mailgun\.(net|org)/v.+@'); Assert::regex($url, '|/attachments/[0-9]+|'); - $response = $this->httpGet($url); + $response = $this->httpGet($url, [], $requestHeaders); if (200 !== $response->getStatusCode()) { $this->handleErrors($response); diff --git a/src/Api/Domain.php b/src/Api/Domain.php index 1bcfc9ce..88a5d8a1 100644 --- a/src/Api/Domain.php +++ b/src/Api/Domain.php @@ -43,14 +43,13 @@ class Domain extends HttpApi /** * Returns a list of domains on the account. - * * @param int $limit * @param int $skip + * @param array $requestHeaders * @return IndexResponse|array * @throws ClientExceptionInterface - * @throws Exception */ - public function index(int $limit = 100, int $skip = 0) + public function index(int $limit = 100, int $skip = 0, array $requestHeaders = []) { Assert::range($limit, 1, 1000); @@ -59,24 +58,23 @@ public function index(int $limit = 100, int $skip = 0) 'skip' => $skip, ]; - $response = $this->httpGet('/v3/domains', $params); + $response = $this->httpGet('/v3/domains', $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Returns a single domain. - * - * @param string $domain name of the domain - * + * @param string $domain name of the domain + * @param array $requestHeaders * @return ShowResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function show(string $domain) + public function show(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/domains/%s', $domain)); + $response = $this->httpGet(sprintf('/v3/domains/%s', $domain), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } @@ -100,8 +98,18 @@ public function show(string $domain) * @return CreateResponse|array|ResponseInterface * @throws Exception */ - public function create(string $domain, string $smtpPass = null, string $spamAction = null, bool $wildcard = null, bool $forceDkimAuthority = null, ?array $ips = null, ?string $pool_id = null, string $webScheme = 'http', string $dkimKeySize = '1024') - { + public function create( + string $domain, + string $smtpPass = null, + string $spamAction = null, + bool $wildcard = null, + bool $forceDkimAuthority = null, + ?array $ips = null, + ?string $pool_id = null, + string $webScheme = 'http', + string $dkimKeySize = '1024', + array $requestHeaders = [] + ) { Assert::stringNotEmpty($domain); $params['name'] = $domain; @@ -113,7 +121,6 @@ public function create(string $domain, string $smtpPass = null, string $spamActi } if (!empty($spamAction)) { - // TODO(sean.johnson): Extended spam filter input validation. Assert::stringNotEmpty($spamAction); $params['spam_action'] = $spamAction; @@ -158,7 +165,7 @@ public function create(string $domain, string $smtpPass = null, string $spamActi $params['dkim_key_size'] = $dkimKeySize; } - $response = $this->httpPost('/v3/domains', $params); + $response = $this->httpPost('/v3/domains', $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } @@ -166,32 +173,30 @@ public function create(string $domain, string $smtpPass = null, string $spamActi /** * Removes a domain from the account. * WARNING: This action is irreversible! Be cautious! - * - * @param string $domain name of the domain - * + * @param string $domain name of the domain + * @param array $requestHeaders * @return DeleteResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function delete(string $domain) + public function delete(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpDelete(sprintf('/v3/domains/%s', $domain)); + $response = $this->httpDelete(sprintf('/v3/domains/%s', $domain), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** * Returns a list of SMTP credentials for the specified domain. - * - * @param string $domain name of the domain - * @param int $limit Number of credentials to return - * @param int $skip Number of credentials to omit from the list - * + * @param string $domain name of the domain + * @param int $limit Number of credentials to return + * @param int $skip Number of credentials to omit from the list + * @param array $requestHeaders * @return CredentialResponse * @throws ClientExceptionInterface */ - public function credentials(string $domain, int $limit = 100, int $skip = 0) + public function credentials(string $domain, int $limit = 100, int $skip = 0, array $requestHeaders = []) { Assert::stringNotEmpty($domain); $params = [ @@ -199,22 +204,21 @@ public function credentials(string $domain, int $limit = 100, int $skip = 0) 'skip' => $skip, ]; - $response = $this->httpGet(sprintf('/v3/domains/%s/credentials', $domain), $params); + $response = $this->httpGet(sprintf('/v3/domains/%s/credentials', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CredentialResponse::class); } /** * Create a new SMTP credential pair for the specified domain. - * - * @param string $domain name of the domain - * @param string $login SMTP Username - * @param string $password SMTP Password. Length min 5, max 32. - * + * @param string $domain name of the domain + * @param string $login SMTP Username + * @param string $password SMTP Password. Length min 5, max 32. + * @param array $requestHeaders * @return CreateCredentialResponse|array|ResponseInterface - * @throws Exception + * @throws ClientExceptionInterface */ - public function createCredential(string $domain, string $login, string $password) + public function createCredential(string $domain, string $login, string $password, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($login); @@ -226,7 +230,7 @@ public function createCredential(string $domain, string $login, string $password 'password' => $password, ]; - $response = $this->httpPost(sprintf('/v3/domains/%s/credentials', $domain), $params); + $response = $this->httpPost(sprintf('/v3/domains/%s/credentials', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateCredentialResponse::class); } @@ -241,7 +245,7 @@ public function createCredential(string $domain, string $login, string $password * @return UpdateCredentialResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function updateCredential(string $domain, string $login, string $pass) + public function updateCredential(string $domain, string $login, string $pass, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($login); @@ -252,21 +256,20 @@ public function updateCredential(string $domain, string $login, string $pass) 'password' => $pass, ]; - $response = $this->httpPut(sprintf('/v3/domains/%s/credentials/%s', $domain, $login), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/credentials/%s', $domain, $login), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateCredentialResponse::class); } /** * Remove a set of SMTP credentials from the specified domain. - * - * @param string $domain name of the domain - * @param string $login SMTP Username - * + * @param string $domain name of the domain + * @param string $login SMTP Username + * @param array $requestHeaders * @return DeleteCredentialResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function deleteCredential(string $domain, string $login) + public function deleteCredential(string $domain, string $login, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($login); @@ -276,7 +279,9 @@ public function deleteCredential(string $domain, string $login) '/v3/domains/%s/credentials/%s', $domain, $login - ) + ), + [], + $requestHeaders ); return $this->hydrateResponse($response, DeleteCredentialResponse::class); @@ -284,17 +289,16 @@ public function deleteCredential(string $domain, string $login) /** * Returns delivery connection settings for the specified domain. - * - * @param string $domain name of the domain - * + * @param string $domain name of the domain + * @param array $requestHeaders * @return ConnectionResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function connection(string $domain) + public function connection(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/domains/%s/connection', $domain)); + $response = $this->httpGet(sprintf('/v3/domains/%s/connection', $domain), [], $requestHeaders); return $this->hydrateResponse($response, ConnectionResponse::class); } @@ -302,15 +306,14 @@ public function connection(string $domain) /** * Updates the specified delivery connection settings for the specified domain. * If a parameter is passed in as null, it will not be updated. - * - * @param string $domain name of the domain - * @param bool|null $requireTLS enforces that messages are sent only over a TLS connection - * @param bool|null $noVerify disables TLS certificate and hostname verification - * + * @param string $domain name of the domain + * @param bool|null $requireTLS enforces that messages are sent only over a TLS connection + * @param bool|null $noVerify disables TLS certificate and hostname verification + * @param array $requestHeaders * @return UpdateConnectionResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function updateConnection(string $domain, ?bool $requireTLS, ?bool $noVerify) + public function updateConnection(string $domain, ?bool $requireTLS, ?bool $noVerify, array $requestHeaders = []) { Assert::stringNotEmpty($domain); $params = []; @@ -323,7 +326,7 @@ public function updateConnection(string $domain, ?bool $requireTLS, ?bool $noVer $params['skip_verification'] = $noVerify ? 'true' : 'false'; } - $response = $this->httpPut(sprintf('/v3/domains/%s/connection', $domain), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/connection', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateConnectionResponse::class); } @@ -332,16 +335,14 @@ public function updateConnection(string $domain, ?bool $requireTLS, ?bool $noVer * Update webScheme for existing domain * See below for spam filtering parameter information. * {@link https://documentation.mailgun.com/user_manual.html#um-spam-filter}. - * * @see https://documentation.mailgun.com/en/latest/api-domains.html#domains - * - * @param string $domain name of the domain - * @param string $webScheme `http` or `https` - set your open, click and unsubscribe URLs to use http or https. The default is http + * @param string $domain name of the domain + * @param string $webScheme `http` or `https` - set your open, click and unsubscribe URLs to use http or https. The default is http + * @param array $requestHeaders * @return WebSchemeResponse|array|ResponseInterface - * @throws Exception * @throws ClientExceptionInterface */ - public function updateWebScheme(string $domain, string $webScheme = 'http') + public function updateWebScheme(string $domain, string $webScheme = 'http', array $requestHeaders = []) { $params = []; Assert::stringNotEmpty($domain); @@ -350,56 +351,52 @@ public function updateWebScheme(string $domain, string $webScheme = 'http') $params['web_scheme'] = $webScheme; - $response = $this->httpPut(sprintf('/v3/domains/%s', $domain), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, WebSchemeResponse::class); } /** * Returns a single domain. - * - * @param string $domain name of the domain - * + * @param string $domain name of the domain + * @param array $requestHeaders * @return VerifyResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function verify(string $domain) + public function verify(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpPut(sprintf('/v3/domains/%s/verify', $domain)); + $response = $this->httpPut(sprintf('/v3/domains/%s/verify', $domain), [], $requestHeaders); return $this->hydrateResponse($response, VerifyResponse::class); } /** * Returns a domain tracking settings. - * - * @param string $domain name of the domain - * + * @param string $domain name of the domain + * @param array $requestHeaders * @return TrackingResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function tracking(string $domain) + public function tracking(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/domains/%s/tracking', $domain)); + $response = $this->httpGet(sprintf('/v3/domains/%s/tracking', $domain), [], $requestHeaders); return $this->hydrateResponse($response, TrackingResponse::class); } /** * Updates a domain click tracking settings. - * - * @param string $domain The name of the domain - * @param string $active The status for this tracking (one of: yes, no) - * + * @param string $domain The name of the domain + * @param string $active The status for this tracking (one of: yes, no) + * @param array $requestHeaders * @return UpdateClickTrackingResponse|array|ResponseInterface - * - * @throws Exception + * @throws ClientExceptionInterface */ - public function updateClickTracking(string $domain, string $active) + public function updateClickTracking(string $domain, string $active, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($active); @@ -409,21 +406,20 @@ public function updateClickTracking(string $domain, string $active) 'active' => $active, ]; - $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/click', $domain), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/click', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateClickTrackingResponse::class); } /** * Updates a domain open tracking settings. - * - * @param string $domain The name of the domain - * @param string $active The status for this tracking (one of: yes, no) - * + * @param string $domain The name of the domain + * @param string $active The status for this tracking (one of: yes, no) + * @param array $requestHeaders * @return UpdateOpenTrackingResponse|array|ResponseInterface * @throws ClientExceptionInterface */ - public function updateOpenTracking(string $domain, string $active) + public function updateOpenTracking(string $domain, string $active, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($active); @@ -433,24 +429,22 @@ public function updateOpenTracking(string $domain, string $active) 'active' => $active, ]; - $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/open', $domain), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/open', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateOpenTrackingResponse::class); } /** * Updates a domain unsubscribe tracking settings. - * - * @param string $domain The name of the domain - * @param string $active The status for this tracking (one of: yes, no) - * @param string $htmlFooter The footer for HTML emails - * @param string $textFooter The footer for plain text emails - * + * @param string $domain The name of the domain + * @param string $active The status for this tracking (one of: yes, no) + * @param string $htmlFooter The footer for HTML emails + * @param string $textFooter The footer for plain text emails + * @param array $requestHeaders * @return UpdateUnsubscribeTrackingResponse|array|ResponseInterface - * - * @throws Exception + * @throws ClientExceptionInterface */ - public function updateUnsubscribeTracking(string $domain, string $active, string $htmlFooter, string $textFooter) + public function updateUnsubscribeTracking(string $domain, string $active, string $htmlFooter, string $textFooter, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($active); @@ -464,7 +458,7 @@ public function updateUnsubscribeTracking(string $domain, string $active, string 'text_footer' => $textFooter, ]; - $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/unsubscribe', $domain), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/tracking/unsubscribe', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateUnsubscribeTrackingResponse::class); } diff --git a/src/Api/EmailValidation.php b/src/Api/EmailValidation.php index 9d261f4a..05b0db03 100644 --- a/src/Api/EmailValidation.php +++ b/src/Api/EmailValidation.php @@ -12,9 +12,6 @@ namespace Mailgun\Api; use Mailgun\Assert; -use Mailgun\Exception\HttpClientException; -use Mailgun\Exception\HttpServerException; -use Mailgun\Exception\InvalidArgumentException; use Mailgun\Model\EmailValidation\ParseResponse; use Mailgun\Model\EmailValidation\ValidateResponse; use Psr\Http\Client\ClientExceptionInterface; @@ -30,17 +27,14 @@ class EmailValidation extends HttpApi /** * Addresses are validated based off defined checks. * This operation is only accessible with the private API key and not subject to the daily usage limits. - * - * @param string $address An email address to validate. Maximum: 512 characters. - * @param bool $mailboxVerification If set to true, a mailbox verification check will be performed - * against the address. The default is False. + * @param string $address An email address to validate. Maximum: 512 characters. + * @param bool $mailboxVerification If set to true, a mailbox verification check will be performed + * against the address. The default is False. + * @param array $requestHeaders * @return ValidateResponse|ResponseInterface - * @throws InvalidArgumentException Thrown when local validation returns an error - * @throws HttpClientException Thrown when there's an error on Client side - * @throws HttpServerException Thrown when there's an error on Server side - * @throws \Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception + * @throws ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception */ - public function validate(string $address, bool $mailboxVerification = false) + public function validate(string $address, bool $mailboxVerification = false, array $requestHeaders = []) { Assert::stringNotEmpty($address); @@ -49,35 +43,27 @@ public function validate(string $address, bool $mailboxVerification = false) 'mailbox_verification' => $mailboxVerification, ]; - $response = $this->httpGet('/v3/address/private/validate', $params); + $response = $this->httpGet('/v3/address/private/validate', $params, $requestHeaders); return $this->hydrateResponse($response, ValidateResponse::class); } /** * Parses a delimiter-separated list of email addresses into two lists: parsed addresses and unparsable portions. - * * The parsed addresses are a list of addresses that are syntactically valid * (and optionally pass DNS and ESP specific grammar checks). - * * The unparsable list is a list of character sequences that could not be parsed * (or optionally failed DNS or ESP specific grammar checks). - * * Delimiter characters are comma (,) and semicolon (;). - * * This operation is only accessible with the private API key and not subject to the daily usage limits. - * - * @param string $addresses A delimiter separated list of addresses. Maximum: 8000 characters. - * @param bool $syntaxOnly Perform only syntax checks or DNS and ESP specific validation as well. - * The default is True. - * + * @param string $addresses A delimiter separated list of addresses. Maximum: 8000 characters. + * @param bool $syntaxOnly Perform only syntax checks or DNS and ESP specific validation as well. + * The default is True. + * @param array $requestHeaders * @return ParseResponse|ResponseInterface - * @throws InvalidArgumentException Thrown when local validation returns an error - * @throws HttpClientException Thrown when there's an error on Client side - * @throws HttpServerException Thrown when there's an error on Server side - * @throws \Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception + * @throws ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception */ - public function parse(string $addresses, bool $syntaxOnly = true) + public function parse(string $addresses, bool $syntaxOnly = true, array $requestHeaders = []) { Assert::stringNotEmpty($addresses); Assert::maxLength($addresses, 8000); @@ -87,7 +73,7 @@ public function parse(string $addresses, bool $syntaxOnly = true) 'syntax_only' => $syntaxOnly, ]; - $response = $this->httpGet('/v3/address/private/parse', $params); + $response = $this->httpGet('/v3/address/private/parse', $params, $requestHeaders); return $this->hydrateResponse($response, ParseResponse::class); } diff --git a/src/Api/EmailValidationV4.php b/src/Api/EmailValidationV4.php index 50792e03..d59e9256 100755 --- a/src/Api/EmailValidationV4.php +++ b/src/Api/EmailValidationV4.php @@ -33,14 +33,14 @@ class EmailValidationV4 extends HttpApi { /** * Addresses are validated based off defined checks. - * * @param string $address An email address to validate. Maximum: 512 characters. * @param bool $providerLookup A provider lookup will be performed if Mailgun’s internal analysis is * insufficient + * @param array $requestHeaders * @return ValidateResponse|ResponseInterface - * @throws Exception|ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception + * @throws ClientExceptionInterface Thrown when we don't catch a Client or Server side Exception */ - public function validate(string $address, bool $providerLookup = true) + public function validate(string $address, bool $providerLookup = true, array $requestHeaders = []) { Assert::stringNotEmpty($address); @@ -49,7 +49,7 @@ public function validate(string $address, bool $providerLookup = true) 'provider_lookup' => $providerLookup, ]; - $response = $this->httpGet('/v4/address/validate', $params); + $response = $this->httpGet('/v4/address/validate', $params, $requestHeaders); return $this->hydrateResponse($response, ValidateResponse::class); } @@ -60,7 +60,7 @@ public function validate(string $address, bool $providerLookup = true) * @return mixed|ResponseInterface * @throws Exception|ClientExceptionInterface */ - public function createBulkJob(string $listId, $filePath) + public function createBulkJob(string $listId, $filePath, array $requestHeaders = []) { Assert::stringNotEmpty($listId); @@ -77,7 +77,7 @@ public function createBulkJob(string $listId, $filePath) $postDataMultipart[] = $this->prepareFile('file', $fileData); try { - $response = $this->httpPostRaw(sprintf('/v4/address/validate/bulk/%s', $listId), $postDataMultipart); + $response = $this->httpPostRaw(sprintf('/v4/address/validate/bulk/%s', $listId), $postDataMultipart, $requestHeaders); } catch (Exception $exception) { throw new RuntimeException($exception->getMessage()); } finally { @@ -88,78 +88,85 @@ public function createBulkJob(string $listId, $filePath) } /** - * @param string $listId ID given when the list created + * @param string $listId ID given when the list created + * @param array $requestHeaders * @return DeleteBulkJobResponse|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function deleteBulkJob(string $listId) + public function deleteBulkJob(string $listId, array $requestHeaders = []) { Assert::stringNotEmpty($listId); - $response = $this->httpDelete(sprintf('/v4/address/validate/bulk/%s', $listId)); + $response = $this->httpDelete(sprintf('/v4/address/validate/bulk/%s', $listId), [], $requestHeaders); return $this->hydrateResponse($response, DeleteBulkJobResponse::class); } /** - * @param string $listId ID given when the list created - * + * @param string $listId ID given when the list created + * @param array $requestHeaders * @return GetBulkJobResponse|ResponseInterface - * - * @throws Exception + * @throws ClientExceptionInterface */ - public function getBulkJob(string $listId) + public function getBulkJob(string $listId, array $requestHeaders = []) { Assert::stringNotEmpty($listId); - $response = $this->httpGet(sprintf('/v4/address/validate/bulk/%s', $listId)); + $response = $this->httpGet(sprintf('/v4/address/validate/bulk/%s', $listId), [], $requestHeaders); return $this->hydrateResponse($response, GetBulkJobResponse::class); } /** - * @param int $limit Jobs limit + * @param int $limit Jobs limit + * @param array $requestHeaders * @return GetBulkJobsResponse|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function getBulkJobs(int $limit = 500) + public function getBulkJobs(int $limit = 500, array $requestHeaders = []) { Assert::greaterThan($limit, 0); $response = $this->httpGet( - '/v4/address/validate/bulk', [ - 'limit' => $limit, - ] + '/v4/address/validate/bulk', + [ + 'limit' => $limit, + ], + $requestHeaders ); return $this->hydrateResponse($response, GetBulkJobsResponse::class); } /** - * @param int $limit Previews Limit + * @param int $limit Previews Limit + * @param array $requestHeaders * @return mixed|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function getBulkPreviews(int $limit = 500) + public function getBulkPreviews(int $limit = 500, array $requestHeaders = []) { Assert::greaterThan($limit, 0); $response = $this->httpGet( - '/v4/address/validate/preview', [ - 'limit' => $limit, - ] + '/v4/address/validate/preview', + [ + 'limit' => $limit, + ], + $requestHeaders ); return $this->hydrateResponse($response, GetBulkPreviewsResponse::class); } /** - * @param string $previewId ID given when the list created - * @param mixed $filePath File path or file content + * @param string $previewId ID given when the list created + * @param mixed $filePath File path or file content + * @param array $requestHeaders * @return mixed|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function createBulkPreview(string $previewId, $filePath) + public function createBulkPreview(string $previewId, $filePath, array $requestHeaders = []) { Assert::stringNotEmpty($previewId); @@ -176,7 +183,7 @@ public function createBulkPreview(string $previewId, $filePath) $postDataMultipart[] = $this->prepareFile('file', $fileData); try { - $response = $this->httpPostRaw(sprintf('/v4/address/validate/preview/%s', $previewId), $postDataMultipart); + $response = $this->httpPostRaw(sprintf('/v4/address/validate/preview/%s', $previewId), $postDataMultipart, $requestHeaders); } catch (Exception $exception) { throw new RuntimeException($exception->getMessage()); } finally { @@ -187,43 +194,46 @@ public function createBulkPreview(string $previewId, $filePath) } /** - * @param string $previewId ID given when the list created + * @param string $previewId ID given when the list created + * @param array $requestHeaders * @return mixed|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function getBulkPreview(string $previewId) + public function getBulkPreview(string $previewId, array $requestHeaders = []) { Assert::stringNotEmpty($previewId); - $response = $this->httpGet(sprintf('/v4/address/validate/preview/%s', $previewId)); + $response = $this->httpGet(sprintf('/v4/address/validate/preview/%s', $previewId), [], $requestHeaders); return $this->hydrateResponse($response, GetBulkPreviewResponse::class); } /** - * @param string $previewId ID given when the list created + * @param string $previewId ID given when the list created + * @param array $requestHeaders * @return bool * @throws ClientExceptionInterface */ - public function deleteBulkPreview(string $previewId): bool + public function deleteBulkPreview(string $previewId, array $requestHeaders = []): bool { Assert::stringNotEmpty($previewId); - $response = $this->httpDelete(sprintf('/v4/address/validate/preview/%s', $previewId)); + $response = $this->httpDelete(sprintf('/v4/address/validate/preview/%s', $previewId), [], $requestHeaders); return 204 === $response->getStatusCode(); } /** - * @param string $previewId ID given when the list created + * @param string $previewId ID given when the list created + * @param array $requestHeaders * @return mixed|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function promoteBulkPreview(string $previewId) + public function promoteBulkPreview(string $previewId, array $requestHeaders = []) { Assert::stringNotEmpty($previewId); - $response = $this->httpPut(sprintf('/v4/address/validate/preview/%s', $previewId)); + $response = $this->httpPut(sprintf('/v4/address/validate/preview/%s', $previewId), [], $requestHeaders); return $this->hydrateResponse($response, PromoteBulkPreviewResponse::class); } diff --git a/src/Api/Event.php b/src/Api/Event.php index c158adc9..d2048a87 100644 --- a/src/Api/Event.php +++ b/src/Api/Event.php @@ -27,10 +27,11 @@ class Event extends HttpApi /** * @param string $domain * @param array $params + * @param array $requestHeaders * @return EventResponse * @throws ClientExceptionInterface */ - public function get(string $domain, array $params = []) + public function get(string $domain, array $params = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); @@ -38,7 +39,7 @@ public function get(string $domain, array $params = []) Assert::range($params['limit'], 1, 300); } - $response = $this->httpGet(sprintf('/v3/%s/events', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/events', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, EventResponse::class); } diff --git a/src/Api/Ip.php b/src/Api/Ip.php index 2dd95e57..6ac31573 100644 --- a/src/Api/Ip.php +++ b/src/Api/Ip.php @@ -27,11 +27,12 @@ class Ip extends HttpApi { /** * Returns a list of IPs. - * + * @param bool|null $dedicated + * @param array $requestHeaders * @return IndexResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function index(?bool $dedicated = null) + public function index(?bool $dedicated = null, array $requestHeaders = []) { $params = []; if (null !== $dedicated) { @@ -39,48 +40,52 @@ public function index(?bool $dedicated = null) $params['dedicated'] = $dedicated; } - $response = $this->httpGet('/v3/ips', $params); + $response = $this->httpGet('/v3/ips', $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Returns a list of IPs assigned to a domain. - * + * @param string $domain + * @param array $requestHeaders * @return IndexResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function domainIndex(string $domain) + public function domainIndex(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/domains/%s/ips', $domain)); + $response = $this->httpGet(sprintf('/v3/domains/%s/ips', $domain), [], $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Returns a single ip. - * + * @param string $ip + * @param array $requestHeaders * @return ShowResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function show(string $ip) + public function show(string $ip, array $requestHeaders = []) { Assert::ip($ip); - $response = $this->httpGet(sprintf('/v3/ips/%s', $ip)); + $response = $this->httpGet(sprintf('/v3/ips/%s', $ip), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** * Assign a dedicated IP to the domain specified. - * + * @param string $domain + * @param string $ip + * @param array $requestHeaders * @return UpdateResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function assign(string $domain, string $ip) + public function assign(string $domain, string $ip, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::ip($ip); @@ -89,23 +94,25 @@ public function assign(string $domain, string $ip) 'ip' => $ip, ]; - $response = $this->httpPost(sprintf('/v3/domains/%s/ips', $domain), $params); + $response = $this->httpPost(sprintf('/v3/domains/%s/ips', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } /** * Unassign an IP from the domain specified. - * + * @param string $domain + * @param string $ip + * @param array $requestHeaders * @return UpdateResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function unassign(string $domain, string $ip) + public function unassign(string $domain, string $ip, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::ip($ip); - $response = $this->httpDelete(sprintf('/v3/domains/%s/ips/%s', $domain, $ip)); + $response = $this->httpDelete(sprintf('/v3/domains/%s/ips/%s', $domain, $ip), [], $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } diff --git a/src/Api/Mailboxes.php b/src/Api/Mailboxes.php index fb6be90f..de570ac8 100644 --- a/src/Api/Mailboxes.php +++ b/src/Api/Mailboxes.php @@ -25,58 +25,69 @@ class Mailboxes extends HttpApi /** * @param string $domain * @param array $parameters + * @param array $requestHeaders * @return CreateResponse * @throws ClientExceptionInterface */ - public function create(string $domain, array $parameters = []) + public function create(string $domain, array $parameters = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::keyExists($parameters, 'mailbox'); Assert::keyExists($parameters, 'password'); Assert::minLength($parameters['password'], self::MIN_PASSWORD_LENGTH); - $response = $this->httpPost(sprintf('/v3/%s/mailboxes', $domain), $parameters); + $response = $this->httpPost(sprintf('/v3/%s/mailboxes', $domain), $parameters, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** + * @param string $domain + * @param array $parameters + * @param array $requestHeaders * @return ShowResponse - * @throws \Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function show(string $domain, array $parameters = []) + public function show(string $domain, array $parameters = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/%s/mailboxes', $domain), $parameters); + $response = $this->httpGet(sprintf('/v3/%s/mailboxes', $domain), $parameters, $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** + * @param string $domain + * @param string $mailbox + * @param array $parameters + * @param array $requestHeaders * @return UpdateResponse - * @throws \Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function update(string $domain, string $mailbox, array $parameters = []) + public function update(string $domain, string $mailbox, array $parameters = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($mailbox); - $response = $this->httpPut(sprintf('/v3/%s/mailboxes/%s', $domain, $mailbox), $parameters); + $response = $this->httpPut(sprintf('/v3/%s/mailboxes/%s', $domain, $mailbox), $parameters, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } /** + * @param string $domain + * @param string $mailbox + * @param array $requestHeaders * @return DeleteResponse - * @throws \Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function delete(string $domain, string $mailbox) + public function delete(string $domain, string $mailbox, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($mailbox); - $response = $this->httpDelete(sprintf('/v3/%s/mailboxes/%s', $domain, $mailbox)); + $response = $this->httpDelete(sprintf('/v3/%s/mailboxes/%s', $domain, $mailbox), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/MailingList.php b/src/Api/MailingList.php index 95bee841..f51c9284 100644 --- a/src/Api/MailingList.php +++ b/src/Api/MailingList.php @@ -39,12 +39,12 @@ public function member(): Member /** * Returns a paginated list of mailing lists on the domain. - * - * @param int $limit Maximum number of records to return (optional: 100 by default) + * @param int $limit Maximum number of records to return (optional: 100 by default) + * @param array $requestHeaders * @return PagesResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function pages(int $limit = 100) + public function pages(int $limit = 100, array $requestHeaders = []) { Assert::range($limit, 1, 1000); @@ -52,24 +52,30 @@ public function pages(int $limit = 100) 'limit' => $limit, ]; - $response = $this->httpGet('/v3/lists/pages', $params); + $response = $this->httpGet('/v3/lists/pages', $params, $requestHeaders); return $this->hydrateResponse($response, PagesResponse::class); } /** * Creates a new mailing list on the current domain. - * - * @param string $address Address for the new mailing list - * @param string|null $name Name for the new mailing list (optional) - * @param string|null $description Description for the new mailing list (optional) - * @param string $accessLevel List access level, one of: readonly (default), members, everyone - * @param string $replyPreference Set where replies should go: list (default) | sender (optional) + * @param string $address Address for the new mailing list + * @param string|null $name Name for the new mailing list (optional) + * @param string|null $description Description for the new mailing list (optional) + * @param string $accessLevel List access level, one of: readonly (default), members, everyone + * @param string $replyPreference Set where replies should go: list (default) | sender (optional) + * @param array $requestHeaders * @return CreateResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function create(string $address, ?string $name = null, ?string $description = null, string $accessLevel = 'readonly', string $replyPreference = 'list') - { + public function create( + string $address, + ?string $name = null, + ?string $description = null, + string $accessLevel = 'readonly', + string $replyPreference = 'list', + array $requestHeaders = [] + ) { Assert::stringNotEmpty($address); Assert::nullOrStringNotEmpty($name); Assert::nullOrStringNotEmpty($description); @@ -84,36 +90,36 @@ public function create(string $address, ?string $name = null, ?string $descripti $description ? $params['description'] = $description : false; $name ? $params['name'] = $name : false; - $response = $this->httpPost('/v3/lists', $params); + $response = $this->httpPost('/v3/lists', $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** * Returns a single mailing list. - * - * @param string $address Address of the mailing list + * @param string $address Address of the mailing list + * @param array $requestHeaders * @return ShowResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function show(string $address) + public function show(string $address, array $requestHeaders = []) { Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/lists/%s', $address)); + $response = $this->httpGet(sprintf('/v3/lists/%s', $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** * Updates a mailing list. - * - * @param string $address Address of the mailing list - * @param array $parameters Array of field => value pairs to update + * @param string $address Address of the mailing list + * @param array $parameters Array of field => value pairs to update + * @param array $requestHeaders * @return UpdateResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function update(string $address, array $parameters = []) + public function update(string $address, array $parameters = [], array $requestHeaders = []) { Assert::stringNotEmpty($address); Assert::isArray($parameters); @@ -133,7 +139,7 @@ public function update(string $address, array $parameters = []) } } - $response = $this->httpPut(sprintf('/v3/lists/%s', $address), $parameters); + $response = $this->httpPut(sprintf('/v3/lists/%s', $address), $parameters, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } @@ -145,59 +151,59 @@ public function update(string $address, array $parameters = []) * @return DeleteResponse * @throws Exception|ClientExceptionInterface */ - public function delete(string $address) + public function delete(string $address, array $requestHeaders = []) { Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/lists/%s', $address)); + $response = $this->httpDelete(sprintf('/v3/lists/%s', $address), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** * Validates mailing list. - * - * @param string $address Address of the mailing list + * @param string $address Address of the mailing list + * @param array $requestHeaders * @return ValidateResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function validate(string $address) + public function validate(string $address, array $requestHeaders = []) { Assert::stringNotEmpty($address); - $response = $this->httpPost(sprintf('/v3/lists/%s/validate', $address)); + $response = $this->httpPost(sprintf('/v3/lists/%s/validate', $address), [], $requestHeaders); return $this->hydrateResponse($response, ValidateResponse::class); } /** * Get mailing list validation status. - * - * @param string $address Address of the mailing list + * @param string $address Address of the mailing list + * @param array $requestHeaders * @return ValidationStatusResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function getValidationStatus(string $address) + public function getValidationStatus(string $address, array $requestHeaders = []) { Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/lists/%s/validate', $address)); + $response = $this->httpGet(sprintf('/v3/lists/%s/validate', $address), [], $requestHeaders); return $this->hydrateResponse($response, ValidationStatusResponse::class); } /** * Cancel mailing list validation. - * - * @param string $address Address of the mailing list + * @param string $address Address of the mailing list + * @param array $requestHeaders * @return ValidationCancelResponse - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function cancelValidation(string $address) + public function cancelValidation(string $address, array $requestHeaders = []) { Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/lists/%s/validate', $address)); + $response = $this->httpDelete(sprintf('/v3/lists/%s/validate', $address), [], $requestHeaders); return $this->hydrateResponse($response, ValidationCancelResponse::class); } diff --git a/src/Api/MailingList/Member.php b/src/Api/MailingList/Member.php index 8ce827e5..b91e949d 100644 --- a/src/Api/MailingList/Member.php +++ b/src/Api/MailingList/Member.php @@ -21,6 +21,7 @@ use Mailgun\Model\MailingList\Member\ShowResponse; use Mailgun\Model\MailingList\Member\UpdateResponse; use Mailgun\Model\MailingList\UpdateResponse as MailingListUpdateResponse; +use Psr\Http\Client\ClientExceptionInterface; /** * @see https://documentation.mailgun.com/en/latest/api-mailinglists.html @@ -31,16 +32,14 @@ class Member extends HttpApi /** * Returns a paginated list of members of the mailing list. - * - * @param string $address Address of the mailing list - * @param int $limit Maximum number of records to return (optional: 100 by default) - * @param bool|null $subscribed `true` to lists subscribed, `false` for unsubscribed. list all if null - * + * @param string $address Address of the mailing list + * @param int $limit Maximum number of records to return (optional: 100 by default) + * @param bool|null $subscribed `true` to lists subscribed, `false` for unsubscribed. list all if null + * @param array $requestHeaders * @return IndexResponse - * - * @throws \Exception + * @throws ClientExceptionInterface */ - public function index(string $address, int $limit = 100, bool $subscribed = null) + public function index(string $address, int $limit = 100, bool $subscribed = null, array $requestHeaders = []) { Assert::stringNotEmpty($address); Assert::greaterThan($limit, 0); @@ -55,44 +54,50 @@ public function index(string $address, int $limit = 100, bool $subscribed = null $params['subscribed'] = 'no'; } - $response = $this->httpGet(sprintf('/v3/lists/%s/members/pages', $address), $params); + $response = $this->httpGet(sprintf('/v3/lists/%s/members/pages', $address), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Shows a single member of the mailing list. - * - * @param string $list Address of the mailing list - * @param string $address Address of the member - * + * @param string $list Address of the mailing list + * @param string $address Address of the member + * @param array $requestHeaders * @return ShowResponse - * - * @throws \Exception + * @throws ClientExceptionInterface */ - public function show(string $list, string $address) + public function show(string $list, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($list); Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/lists/%s/members/%s', $list, $address)); + $response = $this->httpGet(sprintf('/v3/lists/%s/members/%s', $list, $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** * Creates (or updates) a member of the mailing list. - * - * @param string $list Address of the mailing list - * @param string $address Address for the member - * @param string|null $name Name for the member (optional) - * @param array $vars Array of field => value pairs to store additional data - * @param bool $subscribed `true` to add as subscribed (default), `false` as unsubscribed - * @param bool $upsert `true` to update member if present, `false` to raise error in case of a duplicate member (default) + * @param string $list Address of the mailing list + * @param string $address Address for the member + * @param string|null $name Name for the member (optional) + * @param array $vars Array of field => value pairs to store additional data + * @param bool $subscribed `true` to add as subscribed (default), `false` as unsubscribed + * @param bool $upsert `true` to update member if present, `false` to raise error in case of a duplicate member (default) + * @param array $requestHeaders * @return CreateResponse + * @throws ClientExceptionInterface */ - public function create(string $list, string $address, string $name = null, array $vars = [], bool $subscribed = true, bool $upsert = false) - { + public function create( + string $list, + string $address, + string $name = null, + array $vars = [], + bool $subscribed = true, + bool $upsert = false, + array $requestHeaders = [] + ) { Assert::stringNotEmpty($list); Assert::stringNotEmpty($address); Assert::nullOrStringNotEmpty($name); @@ -108,23 +113,21 @@ public function create(string $list, string $address, string $name = null, array $params['name'] = $name; } - $response = $this->httpPost(sprintf('/v3/lists/%s/members', $list), $params); + $response = $this->httpPost(sprintf('/v3/lists/%s/members', $list), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** * Adds multiple members (up to 1000) to the mailing list. - * - * @param string $list Address of the mailing list - * @param array $members Array of members, each item should be either a single string address or an array of member properties - * @param bool $upsert `true` to update existing members, `false` (default) to ignore duplicates - * + * @param string $list Address of the mailing list + * @param array $members Array of members, each item should be either a single string address or an array of member properties + * @param bool $upsert `true` to update existing members, `false` (default) to ignore duplicates + * @param array $requestHeaders * @return UpdateResponse - * - * @throws \Exception + * @throws ClientExceptionInterface */ - public function createMultiple(string $list, array $members, $upsert = false) + public function createMultiple(string $list, array $members, bool $upsert = false, array $requestHeaders = []) { Assert::stringNotEmpty($list); Assert::isArray($members); @@ -165,6 +168,7 @@ public function createMultiple(string $list, array $members, $upsert = false) break; } } + unset($value); } $params = [ @@ -172,7 +176,7 @@ public function createMultiple(string $list, array $members, $upsert = false) 'upsert' => $upsert ? 'yes' : 'no', ]; - $response = $this->httpPost(sprintf('/v3/lists/%s/members.json', $list), $params); + $response = $this->httpPost(sprintf('/v3/lists/%s/members.json', $list), $params, $requestHeaders); return $this->hydrateResponse($response, MailingListUpdateResponse::class); } @@ -188,7 +192,7 @@ public function createMultiple(string $list, array $members, $upsert = false) * * @throws \Exception */ - public function update(string $list, string $address, array $parameters = []) + public function update(string $list, string $address, array $parameters = [], array $requestHeaders = []) { Assert::stringNotEmpty($list); Assert::stringNotEmpty($address); @@ -216,32 +220,31 @@ public function update(string $list, string $address, array $parameters = []) break; } } + unset($value); if (array_key_exists('name', $parameters) && null === $parameters['name']) { unset($parameters['name']); } - $response = $this->httpPut(sprintf('/v3/lists/%s/members/%s', $list, $address), $parameters); + $response = $this->httpPut(sprintf('/v3/lists/%s/members/%s', $list, $address), $parameters, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } /** * Removes a member from the mailing list. - * - * @param string $list Address of the mailing list - * @param string $address Address of the member - * + * @param string $list Address of the mailing list + * @param string $address Address of the member + * @param array $requestHeaders * @return DeleteResponse - * - * @throws \Exception + * @throws ClientExceptionInterface */ - public function delete(string $list, string $address) + public function delete(string $list, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($list); Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/lists/%s/members/%s', $list, $address)); + $response = $this->httpDelete(sprintf('/v3/lists/%s/members/%s', $list, $address), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/Message.php b/src/Api/Message.php index 85ee40c4..8e59dfde 100644 --- a/src/Api/Message.php +++ b/src/Api/Message.php @@ -40,11 +40,13 @@ public function getBatchMessage(string $domain, bool $autoSend = true): BatchMes /** * @see https://documentation.mailgun.com/en/latest/api-sending.html#sending - * + * @param string $domain + * @param array $params + * @param array $requestHeaders * @return SendResponse|ResponseInterface - * @throws Exception|ClientExceptionInterface + * @throws ClientExceptionInterface */ - public function send(string $domain, array $params) + public function send(string $domain, array $params, array $requestHeaders = []) { Assert::string($domain); Assert::notEmpty($domain); @@ -67,7 +69,7 @@ public function send(string $domain, array $params) $postDataMultipart = array_merge($this->prepareMultipartParameters($params), $postDataMultipart); try { - $response = $this->httpPostRaw(sprintf('/v3/%s/messages', $domain), $postDataMultipart); + $response = $this->httpPostRaw(sprintf('/v3/%s/messages', $domain), $postDataMultipart, $requestHeaders); } catch (Exception $exception) { throw new RuntimeException($exception->getMessage()); } finally { @@ -79,15 +81,15 @@ public function send(string $domain, array $params) /** * @see https://documentation.mailgun.com/en/latest/api-sending.html#sending - * - * @param array $recipients with all you send emails to. Including bcc and cc - * @param string $message Message filepath or content - * + * @param string $domain + * @param array $recipients with all you send emails to. Including bcc and cc + * @param string $message Message filepath or content + * @param array $params + * @param array $requestHeaders * @return SendResponse|ResponseInterface * @throws ClientExceptionInterface - * @throws Exception */ - public function sendMime(string $domain, array $recipients, string $message, array $params) + public function sendMime(string $domain, array $recipients, string $message, array $params, array $requestHeaders = []) { Assert::string($domain); Assert::notEmpty($domain); @@ -108,7 +110,7 @@ public function sendMime(string $domain, array $recipients, string $message, arr } $postDataMultipart[] = $this->prepareFile('message', $fileData); try { - $response = $this->httpPostRaw(sprintf('/v3/%s/messages.mime', $domain), $postDataMultipart); + $response = $this->httpPostRaw(sprintf('/v3/%s/messages.mime', $domain), $postDataMultipart, $requestHeaders); } catch (Exception $exception) { throw new RuntimeException($exception->getMessage()); } finally { @@ -120,16 +122,14 @@ public function sendMime(string $domain, array $recipients, string $message, arr /** * Get stored message. - * * @see https://documentation.mailgun.com/en/latest/api-sending.html#retrieving-stored-messages - * - * @param bool $rawMessage if true we will use "Accept: message/rfc2822" header - * + * @param string $url + * @param bool $rawMessage if true we will use "Accept: message/rfc2822" header + * @param array $requestHeaders * @return ShowResponse|ResponseInterface - * @throws Exception * @throws ClientExceptionInterface */ - public function show(string $url, bool $rawMessage = false) + public function show(string $url, bool $rawMessage = false, array $requestHeaders = []) { Assert::notEmpty($url); @@ -137,6 +137,9 @@ public function show(string $url, bool $rawMessage = false) if ($rawMessage) { $headers['Accept'] = 'message/rfc2822'; } + if (!empty($requestHeaders)) { + $headers = array_merge($headers, $requestHeaders); + } $response = $this->httpGet($url, [], $headers); diff --git a/src/Api/Route.php b/src/Api/Route.php index 87f194ba..8b69ec30 100644 --- a/src/Api/Route.php +++ b/src/Api/Route.php @@ -28,13 +28,13 @@ class Route extends HttpApi { /** * Fetches the list of Routes. - * - * @param int $limit Maximum number of records to return. (100 by default) - * @param int $skip Number of records to skip. (0 by default) + * @param int $limit Maximum number of records to return. (100 by default) + * @param int $skip Number of records to skip. (0 by default) + * @param array $requestHeaders * @return IndexResponse * @throws ClientExceptionInterface */ - public function index(int $limit = 100, int $skip = 0) + public function index(int $limit = 100, int $skip = 0, array $requestHeaders = []) { Assert::greaterThan($limit, 0); Assert::greaterThanEq($skip, 0); @@ -45,38 +45,38 @@ public function index(int $limit = 100, int $skip = 0) 'skip' => $skip, ]; - $response = $this->httpGet('/v3/routes', $params); + $response = $this->httpGet('/v3/routes', $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Returns a single Route object based on its ID. - * - * @param string $routeId Route ID returned by the Routes::index() method + * @param string $routeId Route ID returned by the Routes::index() method + * @param array $requestHeaders * @return ShowResponse * @throws ClientExceptionInterface */ - public function show(string $routeId) + public function show(string $routeId, array $requestHeaders = []) { Assert::stringNotEmpty($routeId); - $response = $this->httpGet(sprintf('/v3/routes/%s', $routeId)); + $response = $this->httpGet(sprintf('/v3/routes/%s', $routeId), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** * Creates a new Route. - * - * @param string $expression A filter expression like "match_recipient('.*@gmail.com')" - * @param array $actions Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')" - * @param string $description An arbitrary string - * @param int $priority Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0. + * @param string $expression A filter expression like "match_recipient('.*@gmail.com')" + * @param array $actions Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')" + * @param string $description An arbitrary string + * @param int $priority Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0. + * @param array $requestHeaders * @return CreateResponse * @throws ClientExceptionInterface */ - public function create(string $expression, array $actions, string $description, int $priority = 0) + public function create(string $expression, array $actions, string $description, int $priority = 0, array $requestHeaders = []) { Assert::isArray($actions); @@ -87,7 +87,7 @@ public function create(string $expression, array $actions, string $description, 'description' => $description, ]; - $response = $this->httpPost('/v3/routes', $params); + $response = $this->httpPost('/v3/routes', $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } @@ -95,12 +95,12 @@ public function create(string $expression, array $actions, string $description, /** * Updates a given Route by ID. All parameters are optional. * This API call only updates the specified fields leaving others unchanged. - * - * @param string $routeId Route ID returned by the Routes::index() method - * @param string|null $expression A filter expression like "match_recipient('.*@gmail.com')" - * @param array $actions Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')" - * @param string|null $description An arbitrary string - * @param int|null $priority Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0. + * @param string $routeId Route ID returned by the Routes::index() method + * @param string|null $expression A filter expression like "match_recipient('.*@gmail.com')" + * @param array $actions Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')" + * @param string|null $description An arbitrary string + * @param int|null $priority Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0. + * @param array $requestHeaders * @return UpdateResponse * @throws ClientExceptionInterface */ @@ -109,7 +109,8 @@ public function update( string $expression = null, array $actions = [], string $description = null, - int $priority = null + int $priority = null, + array $requestHeaders = [] ) { Assert::stringNotEmpty($routeId); $params = []; @@ -133,23 +134,23 @@ public function update( $params['priority'] = (string) $priority; } - $response = $this->httpPut(sprintf('/v3/routes/%s', $routeId), $params); + $response = $this->httpPut(sprintf('/v3/routes/%s', $routeId), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } /** * Deletes a Route based on the ID. - * - * @param string $routeId Route ID returned by the Routes::index() method + * @param string $routeId Route ID returned by the Routes::index() method + * @param array $requestHeaders * @return DeleteResponse * @throws ClientExceptionInterface */ - public function delete(string $routeId) + public function delete(string $routeId, array $requestHeaders = []) { Assert::stringNotEmpty($routeId); - $response = $this->httpDelete(sprintf('/v3/routes/%s', $routeId)); + $response = $this->httpDelete(sprintf('/v3/routes/%s', $routeId), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/Stats.php b/src/Api/Stats.php index b7c3ed4f..528b4bbe 100644 --- a/src/Api/Stats.php +++ b/src/Api/Stats.php @@ -23,14 +23,17 @@ class Stats extends HttpApi { /** + * @param string $domain + * @param array $params + * @param array $requestHeaders * @return TotalResponse|array * @throws ClientExceptionInterface */ - public function total(string $domain, array $params = []) + public function total(string $domain, array $params = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpGet(sprintf('/v3/%s/stats/total', rawurlencode($domain)), $params); + $response = $this->httpGet(sprintf('/v3/%s/stats/total', rawurlencode($domain)), $params, $requestHeaders); return $this->hydrateResponse($response, TotalResponse::class); } diff --git a/src/Api/SubAccounts.php b/src/Api/SubAccounts.php new file mode 100644 index 00000000..5fff48de --- /dev/null +++ b/src/Api/SubAccounts.php @@ -0,0 +1,103 @@ +httpPost(self::ENTITY_API_URL, ['name' => $name]); + + return $this->hydrateResponse($response, CreateResponse::class); + } + + /** + * @param array $params + * @return IndexResponse|null + * @throws ClientExceptionInterface + */ + public function index(array $params = []): ?IndexResponse + { + if (isset($params['limit'])) { + Assert::range($params['limit'], 1, 10); + } + if (isset($params['sort'])) { + Assert::isArray($params['sort']); + } + if (isset($params['enabled'])) { + Assert::boolean($params['enabled']); + } + + $response = $this->httpGet(self::ENTITY_API_URL, $params); + + return $this->hydrateResponse($response, IndexResponse::class); + } + + /** + * @param string $id + * @return ShowResponse|null + * @throws ClientExceptionInterface + */ + public function show(string $id): ?ShowResponse + { + Assert::notEmpty($id); + + $response = $this->httpGet(sprintf(self::ENTITY_API_URL.'/%s', $id)); + + return $this->hydrateResponse($response, ShowResponse::class); + } + + /** + * @param string $id + * @return ShowResponse|null + * @throws ClientExceptionInterface + */ + public function disable(string $id): ?ShowResponse + { + Assert::notEmpty($id); + + $response = $this->httpPost(sprintf(self::ENTITY_API_URL.'/%s/disable', $id)); + + return $this->hydrateResponse($response, ShowResponse::class); + } + + /** + * @param string $id + * @return ShowResponse|null + * @throws ClientExceptionInterface + */ + public function enable(string $id): ?ShowResponse + { + Assert::notEmpty($id); + + $response = $this->httpPost(sprintf(self::ENTITY_API_URL.'/%s/enable', $id), ['id' => $id]); + + return $this->hydrateResponse($response, ShowResponse::class); + } +} diff --git a/src/Api/Suppression/Bounce.php b/src/Api/Suppression/Bounce.php index b5760e9a..0269c54f 100644 --- a/src/Api/Suppression/Bounce.php +++ b/src/Api/Suppression/Bounce.php @@ -29,12 +29,13 @@ class Bounce extends HttpApi use Pagination; /** - * @param string $domain Domain to list bounces for - * @param int $limit optional + * @param string $domain Domain to list bounces for + * @param int $limit optional + * @param array $requestHeaders * @return IndexResponse|null * @throws ClientExceptionInterface */ - public function index(string $domain, int $limit = 100): ?IndexResponse + public function index(string $domain, int $limit = 100, array $requestHeaders = []): ?IndexResponse { Assert::stringNotEmpty($domain); Assert::range($limit, 1, 10000, '"Limit" parameter must be between 1 and 10000'); @@ -43,72 +44,76 @@ public function index(string $domain, int $limit = 100): ?IndexResponse 'limit' => $limit, ]; - $response = $this->httpGet(sprintf('/v3/%s/bounces', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/bounces', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** - * @param string $domain Domain to show bounce from - * @param string $address Bounce address to show + * @param string $domain Domain to show bounce from + * @param string $address Bounce address to show + * @param array $requestHeaders * @return ShowResponse|null * @throws ClientExceptionInterface */ - public function show(string $domain, string $address): ?ShowResponse + public function show(string $domain, string $address, array $requestHeaders = []): ?ShowResponse { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/%s/bounces/%s', $domain, $address)); + $response = $this->httpGet(sprintf('/v3/%s/bounces/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** - * @param string $domain Domain to create a bounce for - * @param string $address Address to create a bounce for - * @param array $params optional + * @param string $domain Domain to create a bounce for + * @param string $address Address to create a bounce for + * @param array $params optional + * @param array $requestHeaders * @return CreateResponse|null * @throws ClientExceptionInterface */ - public function create(string $domain, string $address, array $params = []): ?CreateResponse + public function create(string $domain, string $address, array $params = [], array $requestHeaders = []): ?CreateResponse { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); $params['address'] = $address; - $response = $this->httpPost(sprintf('/v3/%s/bounces', $domain), $params); + $response = $this->httpPost(sprintf('/v3/%s/bounces', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** - * @param string $domain Domain to delete a bounce for - * @param string $address Bounce address to delete + * @param string $domain Domain to delete a bounce for + * @param string $address Bounce address to delete + * @param array $requestHeaders * @return DeleteResponse|null * @throws ClientExceptionInterface */ - public function delete(string $domain, string $address): ?DeleteResponse + public function delete(string $domain, string $address, array $requestHeaders = []): ?DeleteResponse { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/%s/bounces/%s', $domain, $address)); + $response = $this->httpDelete(sprintf('/v3/%s/bounces/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** - * @param string $domain Domain to delete all bounces for + * @param string $domain Domain to delete all bounces for + * @param array $requestHeaders * @return DeleteResponse|null * @throws ClientExceptionInterface */ - public function deleteAll(string $domain): ?DeleteResponse + public function deleteAll(string $domain, array $requestHeaders = []): ?DeleteResponse { Assert::stringNotEmpty($domain); - $response = $this->httpDelete(sprintf('/v3/%s/bounces', $domain)); + $response = $this->httpDelete(sprintf('/v3/%s/bounces', $domain), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/Suppression/Complaint.php b/src/Api/Suppression/Complaint.php index e0ff7a4f..7ae319e6 100644 --- a/src/Api/Suppression/Complaint.php +++ b/src/Api/Suppression/Complaint.php @@ -18,6 +18,7 @@ use Mailgun\Model\Suppression\Complaint\DeleteResponse; use Mailgun\Model\Suppression\Complaint\IndexResponse; use Mailgun\Model\Suppression\Complaint\ShowResponse; +use Psr\Http\Client\ClientExceptionInterface; /** * @see https://documentation.mailgun.com/api-suppressions.html#complaints @@ -29,12 +30,13 @@ class Complaint extends HttpApi use Pagination; /** - * @param string $domain Domain to get complaints for - * @param int $limit optional - * + * @param string $domain Domain to get complaints for + * @param int $limit optional + * @param array $requestHeaders * @return IndexResponse + * @throws ClientExceptionInterface */ - public function index(string $domain, int $limit = 100) + public function index(string $domain, int $limit = 100, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::range($limit, 1, 10000, 'Limit parameter must be between 1 and 10000'); @@ -43,7 +45,7 @@ public function index(string $domain, int $limit = 100) 'limit' => $limit, ]; - $response = $this->httpGet(sprintf('/v3/%s/complaints', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/complaints', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } @@ -54,23 +56,24 @@ public function index(string $domain, int $limit = 100) * * @return ShowResponse */ - public function show(string $domain, string $address) + public function show(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/%s/complaints/%s', $domain, $address)); + $response = $this->httpGet(sprintf('/v3/%s/complaints/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** - * @param string $domain Domain to create complaint for - * @param string $address Complaint address - * @param string $createdAt (optional) rfc2822 compliant format. (new \DateTime())->format('r') - * + * @param string $domain Domain to create complaint for + * @param string $address Complaint address + * @param string|null $createdAt (optional) rfc2822 compliant format. (new \DateTime())->format('r') + * @param array $requestHeaders * @return CreateResponse + * @throws ClientExceptionInterface */ - public function create(string $domain, string $address, string $createdAt = null) + public function create(string $domain, string $address, string $createdAt = null, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); @@ -81,37 +84,39 @@ public function create(string $domain, string $address, string $createdAt = null $params['created_at'] = $createdAt; } - $response = $this->httpPost(sprintf('/v3/%s/complaints', $domain), $params); + $response = $this->httpPost(sprintf('/v3/%s/complaints', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** - * @param string $domain Domain to delete complaint for - * @param string $address Complaint address - * + * @param string $domain Domain to delete complaint for + * @param string $address Complaint address + * @param array $requestHeaders * @return DeleteResponse + * @throws ClientExceptionInterface */ - public function delete(string $domain, string $address) + public function delete(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/%s/complaints/%s', $domain, $address)); + $response = $this->httpDelete(sprintf('/v3/%s/complaints/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** - * @param string $domain Domain to delete all bounces for - * + * @param string $domain Domain to delete all bounces for + * @param array $requestHeaders * @return DeleteResponse + * @throws ClientExceptionInterface */ - public function deleteAll(string $domain) + public function deleteAll(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpDelete(sprintf('/v3/%s/complaints', $domain)); + $response = $this->httpDelete(sprintf('/v3/%s/complaints', $domain), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/Suppression/Unsubscribe.php b/src/Api/Suppression/Unsubscribe.php index 92f32475..5d016445 100644 --- a/src/Api/Suppression/Unsubscribe.php +++ b/src/Api/Suppression/Unsubscribe.php @@ -18,6 +18,7 @@ use Mailgun\Model\Suppression\Unsubscribe\DeleteResponse; use Mailgun\Model\Suppression\Unsubscribe\IndexResponse; use Mailgun\Model\Suppression\Unsubscribe\ShowResponse; +use Psr\Http\Client\ClientExceptionInterface; /** * @see https://documentation.mailgun.com/api-suppressions.html#unsubscribes @@ -29,12 +30,13 @@ class Unsubscribe extends HttpApi use Pagination; /** - * @param string $domain Domain to get unsubscribes for - * @param int $limit optional - * + * @param string $domain Domain to get unsubscribes for + * @param int $limit optional + * @param array $requestHeaders * @return IndexResponse + * @throws ClientExceptionInterface */ - public function index(string $domain, int $limit = 100) + public function index(string $domain, int $limit = 100, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::range($limit, 1, 10000, 'Limit parameter must be between 1 and 10000'); @@ -43,54 +45,57 @@ public function index(string $domain, int $limit = 100) 'limit' => $limit, ]; - $response = $this->httpGet(sprintf('/v3/%s/unsubscribes', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/unsubscribes', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** - * @param string $domain Domain to show unsubscribe for - * @param string $address Unsubscribe address - * + * @param string $domain Domain to show unsubscribe for + * @param string $address Unsubscribe address + * @param array $requestHeaders * @return ShowResponse + * @throws ClientExceptionInterface */ - public function show(string $domain, string $address) + public function show(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/%s/unsubscribes/%s', $domain, $address)); + $response = $this->httpGet(sprintf('/v3/%s/unsubscribes/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** - * @param string $domain Domain to create unsubscribe for - * @param string $address Unsubscribe address - * @param array $params optional - * + * @param string $domain Domain to create unsubscribe for + * @param string $address Unsubscribe address + * @param array $params optional + * @param array $requestHeaders * @return CreateResponse + * @throws ClientExceptionInterface */ - public function create(string $domain, string $address, array $params = []) + public function create(string $domain, string $address, array $params = [], array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); $params['address'] = $address; - $response = $this->httpPost(sprintf('/v3/%s/unsubscribes', $domain), $params); + $response = $this->httpPost(sprintf('/v3/%s/unsubscribes', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } /** - * @param string $domain Domain to delete unsubscribe for - * @param string $address Unsubscribe address - * @param string|null $tag Unsubscribe tag - * + * @param string $domain Domain to delete unsubscribe for + * @param string $address Unsubscribe address + * @param string|null $tag Unsubscribe tag + * @param array $requestHeaders * @return DeleteResponse + * @throws ClientExceptionInterface */ - public function delete(string $domain, string $address, string $tag = null) + public function delete(string $domain, string $address, string $tag = null, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); @@ -101,21 +106,22 @@ public function delete(string $domain, string $address, string $tag = null) $params['tag'] = $tag; } - $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes/%s', $domain, $address), $params); + $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes/%s', $domain, $address), $params, $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** - * @param string $domain Domain to delete all unsubscribes for - * + * @param string $domain Domain to delete all unsubscribes for + * @param array $requestHeaders * @return DeleteResponse + * @throws ClientExceptionInterface */ - public function deleteAll(string $domain) + public function deleteAll(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes', $domain)); + $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes', $domain), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/Api/Suppression/Whitelist.php b/src/Api/Suppression/Whitelist.php index 0581c3ac..2ce6bb09 100644 --- a/src/Api/Suppression/Whitelist.php +++ b/src/Api/Suppression/Whitelist.php @@ -21,6 +21,7 @@ use Mailgun\Model\Suppression\Whitelist\ImportResponse; use Mailgun\Model\Suppression\Whitelist\IndexResponse; use Mailgun\Model\Suppression\Whitelist\ShowResponse; +use Psr\Http\Client\ClientExceptionInterface; /** * @see https://documentation.mailgun.com/en/latest/api-suppressions.html#whitelists @@ -32,12 +33,13 @@ class Whitelist extends HttpApi use Pagination; /** - * @param string $domain Domain to get whitelist for - * @param int $limit optional - * + * @param string $domain Domain to get whitelist for + * @param int $limit optional + * @param array $requestHeaders * @return IndexResponse + * @throws ClientExceptionInterface */ - public function index(string $domain, int $limit = 100) + public function index(string $domain, int $limit = 100, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::range($limit, 1, 10000, 'Limit parameter must be between 1 and 10000'); @@ -46,34 +48,36 @@ public function index(string $domain, int $limit = 100) 'limit' => $limit, ]; - $response = $this->httpGet(sprintf('/v3/%s/whitelists', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/whitelists', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** - * @param string $domain Domain to show whitelist for - * @param string $address whitelist address - * + * @param string $domain Domain to show whitelist for + * @param string $address whitelist address + * @param array $requestHeaders * @return ShowResponse + * @throws ClientExceptionInterface */ - public function show(string $domain, string $address) + public function show(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpGet(sprintf('/v3/%s/whitelists/%s', $domain, $address)); + $response = $this->httpGet(sprintf('/v3/%s/whitelists/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** - * @param string $domain Domain to create whitelist for - * @param string $address whitelist email address or domain name - * + * @param string $domain Domain to create whitelist for + * @param string $address whitelist email address or domain name + * @param array $requestHeaders * @return CreateResponse + * @throws ClientExceptionInterface */ - public function create(string $domain, string $address) + public function create(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); @@ -88,7 +92,7 @@ public function create(string $domain, string $address) throw new InvalidArgumentException('Address should be valid email or domain name'); } - $response = $this->httpPost(sprintf('/v3/%s/whitelists', $domain), $params); + $response = $this->httpPost(sprintf('/v3/%s/whitelists', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } @@ -117,31 +121,33 @@ public function import(string $domain, string $filePath) } /** - * @param string $domain Domain to delete whitelist for - * @param string $address whitelist address - * + * @param string $domain Domain to delete whitelist for + * @param string $address whitelist address + * @param array $requestHeaders * @return DeleteResponse + * @throws ClientExceptionInterface */ - public function delete(string $domain, string $address) + public function delete(string $domain, string $address, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($address); - $response = $this->httpDelete(sprintf('/v3/%s/whitelists/%s', $domain, $address)); + $response = $this->httpDelete(sprintf('/v3/%s/whitelists/%s', $domain, $address), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** - * @param string $domain Domain to delete all whitelists for - * + * @param string $domain Domain to delete all whitelists for + * @param array $requestHeaders * @return DeleteAllResponse + * @throws ClientExceptionInterface */ - public function deleteAll(string $domain) + public function deleteAll(string $domain, array $requestHeaders = []) { Assert::stringNotEmpty($domain); - $response = $this->httpDelete(sprintf('/v3/%s/whitelists', $domain)); + $response = $this->httpDelete(sprintf('/v3/%s/whitelists', $domain), [], $requestHeaders); return $this->hydrateResponse($response, DeleteAllResponse::class); } diff --git a/src/Api/Tag.php b/src/Api/Tag.php index efec3ccf..12602ae1 100644 --- a/src/Api/Tag.php +++ b/src/Api/Tag.php @@ -34,11 +34,13 @@ class Tag extends HttpApi /** * Returns a list of tags. - * + * @param string $domain + * @param int $limit + * @param array $requestHeaders * @return IndexResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function index(string $domain, int $limit = 100) + public function index(string $domain, int $limit = 100, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::range($limit, 1, 1000); @@ -47,34 +49,39 @@ public function index(string $domain, int $limit = 100) 'limit' => $limit, ]; - $response = $this->httpGet(sprintf('/v3/%s/tags', $domain), $params); + $response = $this->httpGet(sprintf('/v3/%s/tags', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } /** * Returns a single tag. - * + * @param string $domain + * @param string $tag + * @param array $requestHeaders * @return ShowResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function show(string $domain, string $tag) + public function show(string $domain, string $tag, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpGet(sprintf('/v3/%s/tags/%s', $domain, $tag)); + $response = $this->httpGet(sprintf('/v3/%s/tags/%s', $domain, $tag), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } /** * Update a tag. - * + * @param string $domain + * @param string $tag + * @param string $description + * @param array $requestHeaders * @return UpdateResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function update(string $domain, string $tag, string $description) + public function update(string $domain, string $tag, string $description, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); @@ -83,81 +90,95 @@ public function update(string $domain, string $tag, string $description) 'description' => $description, ]; - $response = $this->httpPut(sprintf('/v3/%s/tags/%s', $domain, $tag), $params); + $response = $this->httpPut(sprintf('/v3/%s/tags/%s', $domain, $tag), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } /** * Returns statistics for a single tag. - * + * @param string $domain + * @param string $tag + * @param array $params + * @param array $requestHeaders * @return StatisticsResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function stats(string $domain, string $tag, array $params) + public function stats(string $domain, string $tag, array $params, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats', $domain, $tag), $params); + $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats', $domain, $tag), $params, $requestHeaders); return $this->hydrateResponse($response, StatisticsResponse::class); } /** * Removes a tag from the account. - * + * @param string $domain + * @param string $tag + * @param array $requestHeaders * @return DeleteResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function delete(string $domain, string $tag) + public function delete(string $domain, string $tag, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpDelete(sprintf('/v3/%s/tags/%s', $domain, $tag)); + $response = $this->httpDelete(sprintf('/v3/%s/tags/%s', $domain, $tag), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } /** + * @param string $domain + * @param string $tag + * @param array $requestHeaders * @return CountryResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function countries(string $domain, string $tag) + public function countries(string $domain, string $tag, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/countries', $domain, $tag)); + $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/countries', $domain, $tag), [], $requestHeaders); return $this->hydrateResponse($response, CountryResponse::class); } /** + * @param string $domain + * @param string $tag + * @param array $requestHeaders * @return ProviderResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function providers(string $domain, string $tag) + public function providers(string $domain, string $tag, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/providers', $domain, $tag)); + $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/providers', $domain, $tag), [], $requestHeaders); return $this->hydrateResponse($response, ProviderResponse::class); } /** + * @param string $domain + * @param string $tag + * @param array $requestHeaders * @return DeviceResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function devices(string $domain, string $tag) + public function devices(string $domain, string $tag, array $requestHeaders = []) { Assert::stringNotEmpty($domain); Assert::stringNotEmpty($tag); - $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/devices', $domain, $tag)); + $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/devices', $domain, $tag), [], $requestHeaders); return $this->hydrateResponse($response, DeviceResponse::class); } diff --git a/src/Api/Webhook.php b/src/Api/Webhook.php index 1e4e86c7..232df427 100644 --- a/src/Api/Webhook.php +++ b/src/Api/Webhook.php @@ -75,13 +75,14 @@ public function verifyWebhookSignature(int $timestamp, string $token, string $si /** * @param string $domain + * @param array $requestHeaders * @return IndexResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function index(string $domain) + public function index(string $domain, array $requestHeaders = []) { Assert::notEmpty($domain); - $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks', $domain)); + $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks', $domain), [], $requestHeaders); return $this->hydrateResponse($response, IndexResponse::class); } @@ -89,14 +90,15 @@ public function index(string $domain) /** * @param string $domain * @param string $webhook + * @param array $requestHeaders * @return ShowResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function show(string $domain, string $webhook) + public function show(string $domain, string $webhook, array $requestHeaders = []) { Assert::notEmpty($domain); Assert::notEmpty($webhook); - $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks/%s', $domain, $webhook)); + $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks/%s', $domain, $webhook), [], $requestHeaders); return $this->hydrateResponse($response, ShowResponse::class); } @@ -105,10 +107,11 @@ public function show(string $domain, string $webhook) * @param string $domain * @param string $id * @param array $url + * @param array $requestHeaders * @return CreateResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function create(string $domain, string $id, array $url) + public function create(string $domain, string $id, array $url, array $requestHeaders = []) { Assert::notEmpty($domain); Assert::notEmpty($id); @@ -119,7 +122,7 @@ public function create(string $domain, string $id, array $url) 'url' => $url, ]; - $response = $this->httpPost(sprintf('/v3/domains/%s/webhooks', $domain), $params); + $response = $this->httpPost(sprintf('/v3/domains/%s/webhooks', $domain), $params, $requestHeaders); return $this->hydrateResponse($response, CreateResponse::class); } @@ -128,10 +131,11 @@ public function create(string $domain, string $id, array $url) * @param string $domain * @param string $id * @param array $url + * @param array $requestHeaders * @return UpdateResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function update(string $domain, string $id, array $url) + public function update(string $domain, string $id, array $url, array $requestHeaders = []) { Assert::notEmpty($domain); Assert::notEmpty($id); @@ -141,7 +145,7 @@ public function update(string $domain, string $id, array $url) 'url' => $url, ]; - $response = $this->httpPut(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id), $params); + $response = $this->httpPut(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id), $params, $requestHeaders); return $this->hydrateResponse($response, UpdateResponse::class); } @@ -149,15 +153,16 @@ public function update(string $domain, string $id, array $url) /** * @param string $domain * @param string $id + * @param array $requestHeaders * @return DeleteResponse|ResponseInterface * @throws ClientExceptionInterface */ - public function delete(string $domain, string $id) + public function delete(string $domain, string $id, array $requestHeaders = []) { Assert::notEmpty($domain); Assert::notEmpty($id); - $response = $this->httpDelete(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id)); + $response = $this->httpDelete(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id), [], $requestHeaders); return $this->hydrateResponse($response, DeleteResponse::class); } diff --git a/src/HttpClient/HttpClientConfigurator.php b/src/HttpClient/HttpClientConfigurator.php index 3fbc045b..e2eff912 100644 --- a/src/HttpClient/HttpClientConfigurator.php +++ b/src/HttpClient/HttpClientConfigurator.php @@ -60,6 +60,11 @@ final class HttpClientConfigurator */ private $responseHistory; + /** + * @var ?string + */ + private $subAccountId; + public function __construct() { $this->responseHistory = new History(); @@ -74,14 +79,18 @@ public function createConfiguredClient(): PluginClient if (!isset($userAgent) || !$userAgent) { $userAgent = 'mailgun-sdk-php/v2 (https://github.com/mailgun/mailgun-php)'; } + + $defaultPlugin = [ + 'User-Agent' => $userAgent, + 'Authorization' => 'Basic '.base64_encode(sprintf('api:%s', $this->getApiKey())), + ]; + if (null !== $this->getSubAccountId()) { + $defaultPlugin['X-Mailgun-On-Behalf-Of'] = $this->getSubAccountId(); + } + $plugins = [ new Plugin\AddHostPlugin($this->getUriFactory()->createUri($this->endpoint)), - new Plugin\HeaderDefaultsPlugin( - [ - 'User-Agent' => $userAgent, - 'Authorization' => 'Basic '.base64_encode(sprintf('api:%s', $this->getApiKey())), - ] - ), + new Plugin\HeaderDefaultsPlugin($defaultPlugin), new Plugin\HistoryPlugin($this->responseHistory), ]; @@ -154,4 +163,23 @@ public function getResponseHistory(): History { return $this->responseHistory; } + + /** + * @return string|null + */ + public function getSubAccountId(): ?string + { + return $this->subAccountId; + } + + /** + * @param string|null $subAccountId + * @return HttpClientConfigurator + */ + public function setSubAccountId(?string $subAccountId): self + { + $this->subAccountId = $subAccountId; + + return $this; + } } diff --git a/src/Mailgun.php b/src/Mailgun.php index eb2d22a5..2da25ad6 100644 --- a/src/Mailgun.php +++ b/src/Mailgun.php @@ -86,15 +86,17 @@ public function __construct( } /** - * @param string $apiKey - * @param string $endpoint + * @param string $apiKey + * @param string $endpoint + * @param string|null $subAccountId * @return self */ - public static function create(string $apiKey, string $endpoint = 'https://api.mailgun.net'): self + public static function create(string $apiKey, string $endpoint = 'https://api.mailgun.net', ?string $subAccountId = null): self { $httpClientConfigurator = (new HttpClientConfigurator()) ->setApiKey($apiKey) - ->setEndpoint($endpoint); + ->setEndpoint($endpoint) + ->setSubAccountId($subAccountId); return new self($httpClientConfigurator); } @@ -226,4 +228,9 @@ public function httpClient(): Api\HttpClient { return new Api\HttpClient($this->httpClient, $this->requestBuilder, $this->hydrator); } + + public function subaccounts(): Api\SubAccounts + { + return new Api\SubAccounts($this->httpClient, $this->requestBuilder, $this->hydrator); + } } diff --git a/src/Model/SubAccounts/BaseResponse.php b/src/Model/SubAccounts/BaseResponse.php new file mode 100644 index 00000000..e55152d1 --- /dev/null +++ b/src/Model/SubAccounts/BaseResponse.php @@ -0,0 +1,58 @@ + + */ +abstract class BaseResponse implements ApiResponse +{ + private $address; + private $message; + + final private function __construct() + { + } + + /** + * @param array $data + * @return static + */ + public static function create(array $data): self + { + $model = new static(); + $model->address = $data['address'] ?? ''; + $model->message = $data['message'] ?? ''; + + return $model; + } + + /** + * @return string + */ + public function getAddress(): string + { + return $this->address; + } + + /** + * @return string + */ + public function getMessage(): string + { + return $this->message; + } +} diff --git a/src/Model/SubAccounts/CreateResponse.php b/src/Model/SubAccounts/CreateResponse.php new file mode 100644 index 00000000..82d9e8e2 --- /dev/null +++ b/src/Model/SubAccounts/CreateResponse.php @@ -0,0 +1,75 @@ +setMessage(isset($data['message']) ? [$data['message']] : $data); + + return $model; + } + + /** + * @return array + */ + public function getMessage(): array + { + return $this->message; + } + + /** + * @param array $message + */ + public function setMessage(array $message): void + { + $this->message = $message; + } + + /** + * @return array + */ + public function getError(): array + { + return $this->error; + } + + /** + * @param array $error + */ + public function setError(array $error): void + { + $this->error = $error; + } +} diff --git a/src/Model/SubAccounts/IndexResponse.php b/src/Model/SubAccounts/IndexResponse.php new file mode 100644 index 00000000..8a0beacb --- /dev/null +++ b/src/Model/SubAccounts/IndexResponse.php @@ -0,0 +1,72 @@ +items = $items; + $model->total = (int) ($data['total'] ?? 0); + + return $model; + } + + /** + * @return SubAccount[] + */ + public function getItems(): array + { + return $this->items; + } + + /** + * @return int + */ + public function getTotal(): int + { + return $this->total; + } +} diff --git a/src/Model/SubAccounts/ShowResponse.php b/src/Model/SubAccounts/ShowResponse.php new file mode 100644 index 00000000..8f1f92d2 --- /dev/null +++ b/src/Model/SubAccounts/ShowResponse.php @@ -0,0 +1,78 @@ + + */ +final class ShowResponse implements ApiResponse +{ + /** + * @var SubAccount + */ + private $item; + + /** + * @var array + */ + private $message; + + /** + * @param array $data + * @return ShowResponse + * @throws \Exception + */ + public static function create(array $data): self + { + $model = new self(); + $model->setItem(SubAccount::create($data['subaccount'] ?? [])); + if (isset($data['message'])) { + $model->setMessage([$data['message']]); + } + + return $model; + } + + /** + * @return SubAccount + */ + public function getItem(): SubAccount + { + return $this->item; + } + + /** + * @param SubAccount $item + */ + public function setItem(SubAccount $item): void + { + $this->item = $item; + } + + /** + * @return array + */ + public function getMessage(): array + { + return $this->message; + } + + /** + * @param array $message + */ + public function setMessage(array $message): void + { + $this->message = $message; + } +} diff --git a/src/Model/SubAccounts/SubAccount.php b/src/Model/SubAccounts/SubAccount.php new file mode 100644 index 00000000..49ff6975 --- /dev/null +++ b/src/Model/SubAccounts/SubAccount.php @@ -0,0 +1,110 @@ + + */ +class SubAccount +{ + /** + * @var string + */ + private $id; + + /** + * @var string + */ + private $name; + + /** + * @var string + */ + private $status; + + final private function __construct() + { + } + + /** + * @throws \Exception + */ + public static function create(array $data): self + { + $model = new self(); + $model->setStatus($data['status'] ?? ''); + $model->setId($data['id'] ?? ''); + $model->setName($data['name'] ?? ''); + + return $model; + } + + /** + * @return string + */ + public function getId(): string + { + return $this->id; + } + + /** + * @param string $id + */ + public function setId(string $id): void + { + $this->id = $id; + } + + /** + * @return string + */ + public function getName(): string + { + return $this->name; + } + + /** + * @param string $name + */ + public function setName(string $name): void + { + $this->name = $name; + } + + /** + * @return string + */ + public function getStatus(): string + { + return $this->status; + } + + /** + * @param string $status + */ + public function setStatus(string $status): void + { + $this->status = $status; + } + + /** + * @return array + */ + public function toArray(): array + { + return [ + 'id' => $this->getId(), + 'name' => $this->getName(), + 'status' => $this->getStatus(), + ]; + } +} diff --git a/tests/Api/DomainTest.php b/tests/Api/DomainTest.php index 777eeb52..e2bb69c1 100644 --- a/tests/Api/DomainTest.php +++ b/tests/Api/DomainTest.php @@ -262,7 +262,7 @@ public function testDeleteCredential() $this->setHydrateClass(DeleteCredentialResponse::class); $api = $this->getApiInstance(); - $api->deleteCredential('example.com', 'foo', 'barbar'); + $api->deleteCredential('example.com', 'foo'); } public function testConnection()