Skip to content

Commit 2ef202c

Browse files
authored
Merge pull request #2 from xqueue/feature/refactor
1.0.0
2 parents cfe2637 + cfeced2 commit 2ef202c

25 files changed

+255
-145
lines changed

README.md

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,143 @@
1-
# partner-php-api-client
1+
# Maileon Partner API Client
2+
3+
Provides an API client to connect to XQueue Maileon's Partner REST API and (de-)serializes all API functions and data for easier use in PHP projects.
4+
5+
Maileon's REST API documentation can be found [here](https://support.maileon.com/support/partner-api/).
6+
7+
## Table of contents
8+
* [Requirements](#requirements)
9+
* [Installation](#installation)
10+
* [Usage](#usage)
11+
* [Examples](#examples)
12+
* [Tests](#tests)
13+
14+
15+
## Requirements
16+
The API client requires `PHP >= 8.1` with `libcurl`.
17+
18+
Additionally all requests use an SSL encrypted API endpoint.
19+
To enable SSL support in CURL, please follow these steps:
20+
1. Download the official SSL cert bundle by CURL from https://curl.haxx.se/ca/cacert.pem
21+
2. Save the bundle to a directory that can be accessed by your PHP installation
22+
3. Add the following entry to your php.ini (remember to change the path to where you put the cert bundle):
23+
```
24+
curl.cainfo="your-path-to-the-bundle/cacert.pem"
25+
```
26+
27+
## Installation
28+
29+
You can add this library to your project using [Composer](https://getcomposer.org/):
30+
31+
```
32+
composer require xqueue/maileon-partner-api-client
33+
```
34+
35+
## Usage
36+
37+
The API client divides the features of Maileon's Partner REST API into specific consumable services. Each service provides all functions of it's specific category.
38+
* **AccountService:**
39+
* Manage newsletter and customer accounts, api keys, mailing domains.
40+
41+
42+
* **BlacklistService:**
43+
* Manage your blacklists.
44+
45+
46+
* **ContingentService:**
47+
* Manage contingents and prepaid status.
48+
49+
50+
* **DistributorReportService:**
51+
* Get Volume and SMS Reports.
52+
53+
54+
* **GeneralService:**
55+
* Get domains list, validate domain, get locales.
56+
57+
58+
* **JobService:**
59+
* Get jobs, create account job.
60+
61+
62+
* **ProductService:**
63+
* Manage products and upload templates.
64+
65+
66+
* **ReportService:**
67+
* Get report checks and report CSAs.
68+
69+
70+
* **RoleService:**
71+
* Create or delete custom roles.
72+
73+
74+
* **UserService:**
75+
* Manage user accounts and roles.
76+
77+
78+
* **WebhookService:**
79+
* Manage webhooks.
80+
81+
## Examples
82+
Get Newsletter Accounts:
83+
```php
84+
$service = new AccountService(['API_KEY' => 'Your API key'])
85+
86+
$response = $service->getNewsletterAccounts();
87+
88+
if(!$response->getResponse()->isSuccess()){
89+
// handle error
90+
}
91+
92+
$newsletterAccounts = $response->getData();
93+
```
94+
95+
Create Job:
96+
```php
97+
$service = new JobService(['API_KEY' => 'Your API key'])
98+
99+
$response = $this->jobService->createAccountJob(
100+
$locale,
101+
$type,
102+
$author,
103+
$customerAccountName,
104+
$newsletterAccountName,
105+
$customDomain ?? null,
106+
$providedDomain ?? null,
107+
$subdomain ?? null,
108+
$customDns ?? null,
109+
$accountTemplateId ?? null,
110+
$users ?? null,
111+
$customerAccountId ?? null,
112+
$domainAsLogin ?? null
113+
);
114+
115+
if(!$response->getResponse()->isSuccess()){
116+
// handle error
117+
}
118+
119+
$data = $response->getData();
120+
$jobId = $data['jobId'];
121+
```
122+
123+
124+
## Tests
125+
In order to run the unit tests you need to have Docker installed.
126+
127+
First you need to create a .env file and add your API key:
128+
```dotenv
129+
MAILEON_PARTNER_API_KEY=**********
130+
```
131+
132+
Run the following commands to create the container and install the required packages:
133+
```
134+
docker-compose up -d
135+
136+
docker exec -it partner-api composer install
137+
```
138+
139+
Run the following commands to run the tests:
140+
```shell
141+
docker exec -it partner-api composer test
142+
docker exec -it partner-api composer test-coverage // or this if you want to have the coverage generated
143+
```

composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,5 +55,5 @@
5555
"config": {
5656
"sort-packages": true
5757
},
58-
"version": "0.0.1"
58+
"version": "1.0.0"
5959
}

phpdocker/php-fpm/Dockerfile

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
FROM webdevops/php-nginx-dev:8.2
22

3-
RUN echo date.timezone = "Europe/Budapest" >> /opt/docker/etc/php/php.ini
4-
53
WORKDIR "/app"
64
COPY . /app
75

src/Http/Request.php

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,25 @@
44

55
class Request
66
{
7-
public const BASE_URL = 'https://api-test.maileon.com/partner/';
8-
97
/**
10-
* @param string $method
11-
* @param string $url
12-
* @param array $params
13-
* @param array $body
14-
* @param string|null $apiKey
8+
* @param string $method
9+
* @param string $url
10+
* @param array $params
11+
* @param array $body
12+
* @param array $config
1513
*
1614
* @return ApiResponse
1715
*/
1816
public static function send(
19-
string $method,
20-
string $url,
21-
array $params = [],
22-
array $body = [],
23-
?string $apiKey = '',
17+
string $method,
18+
string $url,
19+
array $params = [],
20+
array $body = [],
21+
array $config = []
2422
): ApiResponse {
25-
$params['key'] = $apiKey;
23+
$params['key'] = $config['API_KEY'];
2624
$queryString = http_build_query($params);
27-
$fullUrl = self::BASE_URL . $url . ($queryString ? '?' . $queryString : '');
25+
$fullUrl = $config['BASE_URI'] . $url . ($queryString ? '?' . $queryString : '');
2826

2927
$curl = curl_init();
3028
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
@@ -36,6 +34,8 @@ public static function send(
3634
curl_setopt($curl, CURLOPT_URL, $fullUrl);
3735
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
3836
curl_setopt($curl, CURLOPT_HEADER, true);
37+
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $config['TIMEOUT']);
38+
curl_setopt($curl, CURLOPT_TIMEOUT, $config['TIMEOUT']);
3939

4040
$response = curl_exec($curl);
4141
$error = curl_error($curl);

src/Services/AccountService.php

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
use Xqueue\MaileonPartnerApiClient\Entities\CustomerAccount;
99
use Xqueue\MaileonPartnerApiClient\Entities\MailingDomain;
1010
use Xqueue\MaileonPartnerApiClient\Entities\NewsletterAccount;
11-
use Xqueue\MaileonPartnerApiClient\Http\Request;
1211
use Xqueue\MaileonPartnerApiClient\Http\Responses\AccountStatusResponse;
1312
use Xqueue\MaileonPartnerApiClient\Http\Responses\ApiKeyResponse;
1413
use Xqueue\MaileonPartnerApiClient\Http\Responses\CustomerAccountResponse;
@@ -192,12 +191,10 @@ public function getNewsletterAccount(int $id): NewsletterAccountResponse
192191
*/
193192
public function setNewsletterAccountStatus(int $id, string $status): AccountStatusResponse
194193
{
195-
$response = Request::send(
194+
$response = $this->sendRequest(
196195
'POST',
197196
'newsletter-accounts/' . $id . '/status',
198-
['status' => $status],
199-
[],
200-
$this->key
197+
['status' => $status]
201198
);
202199

203200
$data = $this->mapObject(AccountStatus::class, $response->body);
@@ -243,12 +240,9 @@ public function addMailingDomainToNewsletterAccount(
243240
int $newsletterAccountId,
244241
string $mailingDomainName
245242
): GeneralResponse {
246-
$response = Request::send(
243+
$response = $this->sendRequest(
247244
'POST',
248245
'newsletter-accounts/' . $newsletterAccountId . '/mailing-domains/' . urlencode($mailingDomainName),
249-
[],
250-
[],
251-
$this->key
252246
);
253247

254248
return new GeneralResponse($response->body, $response);
@@ -262,13 +256,9 @@ public function addMailingDomainToNewsletterAccount(
262256
*/
263257
public function getStatusOfMailingDomain(int $newsletterAccountId, string $mailingDomain): GeneralResponse
264258
{
265-
$response = Request::send(
259+
$response = $this->sendRequest(
266260
'GET',
267-
'newsletter-accounts/' . $newsletterAccountId . '/mailing-domains/' .
268-
urlencode($mailingDomain) . '/status',
269-
[],
270-
[],
271-
$this->key
261+
'newsletter-accounts/' . $newsletterAccountId . '/mailing-domains/' . urlencode($mailingDomain) . '/status',
272262
);
273263

274264
return new GeneralResponse($response->body, $response);
@@ -286,13 +276,10 @@ public function setStatusOfMailingDomain(
286276
string $mailingDomain,
287277
string $status
288278
): GeneralResponse {
289-
$response = Request::send(
279+
$response = $this->sendRequest(
290280
'PUT',
291-
'newsletter-accounts/' . $newsletterAccountId . '/mailing-domains/' .
292-
urlencode($mailingDomain) . '/status',
293-
['newStatus' => $status],
294-
[],
295-
$this->key
281+
'newsletter-accounts/' . $newsletterAccountId . '/mailing-domains/' . urlencode($mailingDomain) . '/status',
282+
['newStatus' => $status]
296283
);
297284

298285
return new GeneralResponse($response->body, $response);

src/Services/BlacklistService.php

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
use CuyZ\Valinor\Mapper\MappingError;
66
use Xqueue\MaileonPartnerApiClient\Entities\Blacklist;
7-
use Xqueue\MaileonPartnerApiClient\Http\Request;
87
use Xqueue\MaileonPartnerApiClient\Http\Responses\BlacklistResponse;
98
use Xqueue\MaileonPartnerApiClient\Http\Responses\GeneralResponse;
109

@@ -83,16 +82,14 @@ public function getBlacklist(int $id): BlacklistResponse
8382
*/
8483
public function updateBlacklist(int $id, string $name, string $status, ?string $type = null): BlacklistResponse
8584
{
86-
$response = Request::send(
85+
$response = $this->sendRequest(
8786
'PUT',
8887
'blacklists/' . $id,
8988
[
9089
'name' => $name,
9190
'status' => $status,
9291
'type' => $type,
93-
],
94-
[],
95-
$this->key
92+
]
9693
);
9794

9895
$data = $this->mapObject(Blacklist::class, $response->body);
@@ -107,7 +104,7 @@ public function updateBlacklist(int $id, string $name, string $status, ?string $
107104
*/
108105
public function deleteBlacklist(int $id): GeneralResponse
109106
{
110-
$response = Request::send('DELETE', 'blacklists/' . $id, [], [], $this->key);
107+
$response = $this->sendRequest('DELETE', 'blacklists/' . $id);
111108

112109
return new GeneralResponse($response->body, $response);
113110
}
@@ -119,7 +116,7 @@ public function deleteBlacklist(int $id): GeneralResponse
119116
*/
120117
public function getAccountsOfBlacklist(int $id): GeneralResponse
121118
{
122-
$response = Request::send('GET', 'blacklists/' . $id . '/accounts', [], [], $this->key);
119+
$response = $this->sendRequest('GET', 'blacklists/' . $id . '/accounts');
123120

124121
return new GeneralResponse($response->body, $response);
125122
}
@@ -132,12 +129,10 @@ public function getAccountsOfBlacklist(int $id): GeneralResponse
132129
*/
133130
public function addAccountsToBlacklist(int $id, array $newsletterAccountIds): GeneralResponse
134131
{
135-
$response = Request::send(
132+
$response = $this->sendRequest(
136133
'POST',
137134
'blacklists/' . $id . '/accounts',
138-
['newsletterAccountIds' => implode(',', $newsletterAccountIds)],
139-
[],
140-
$this->key
135+
['newsletterAccountIds' => implode(',', $newsletterAccountIds)]
141136
);
142137

143138
return new GeneralResponse($response->body, $response);
@@ -152,12 +147,10 @@ public function addAccountsToBlacklist(int $id, array $newsletterAccountIds): Ge
152147
*/
153148
public function getPatternsOfBlacklist(int $id, int $pageIndex, int $pageSize): GeneralResponse
154149
{
155-
$response = Request::send(
150+
$response = $this->sendRequest(
156151
'GET',
157152
'blacklists/' . $id . '/patterns',
158-
['page_size' => $pageSize, 'page_index' => $pageIndex],
159-
[],
160-
$this->key
153+
['page_size' => $pageSize, 'page_index' => $pageIndex]
161154
);
162155

163156
return new GeneralResponse($response->body, $response);
@@ -172,12 +165,11 @@ public function getPatternsOfBlacklist(int $id, int $pageIndex, int $pageSize):
172165
*/
173166
public function updatePatternsOfBlacklist(int $id, string $uploadName, array $patterns): GeneralResponse
174167
{
175-
$response = Request::send(
168+
$response = $this->sendRequest(
176169
'POST',
177170
'blacklists/' . $id . '/patterns',
178171
[],
179172
['uploadName' => $uploadName, 'patterns' => $patterns],
180-
$this->key
181173
);
182174

183175
return new GeneralResponse($response->body, $response);

0 commit comments

Comments
 (0)