1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
declare(strict_types=1); |
4
|
|
|
|
5
|
|
|
/* |
6
|
|
|
* Copyright (C) 2013 Mailgun |
7
|
|
|
* |
8
|
|
|
* This software may be modified and distributed under the terms |
9
|
|
|
* of the MIT license. See the LICENSE file for details. |
10
|
|
|
*/ |
11
|
|
|
|
12
|
|
|
namespace Mailgun\Api\MailingList; |
13
|
|
|
|
14
|
|
|
use Mailgun\Api\HttpApi; |
15
|
|
|
use Mailgun\Assert; |
16
|
|
|
use Mailgun\Exception\InvalidArgumentException; |
17
|
|
|
use Mailgun\Model\MailingList\Member\CreateResponse; |
18
|
|
|
use Mailgun\Model\MailingList\Member\DeleteResponse; |
19
|
|
|
use Mailgun\Model\MailingList\Member\IndexResponse; |
20
|
|
|
use Mailgun\Model\MailingList\Member\ShowResponse; |
21
|
|
|
use Mailgun\Model\MailingList\Member\UpdateResponse; |
22
|
|
|
use Mailgun\Model\MailingList\UpdateResponse as MailingListUpdateResponse; |
23
|
|
|
|
24
|
|
|
/** |
25
|
|
|
* @see https://documentation.mailgun.com/en/latest/api-mailinglists.html |
26
|
|
|
*/ |
27
|
|
|
class Member extends HttpApi |
28
|
|
|
{ |
29
|
|
|
/** |
30
|
|
|
* Returns a paginated list of members of the mailing list. |
31
|
|
|
* |
32
|
|
|
* @param string $address Address of the mailing list |
33
|
|
|
* @param int $limit Maximum number of records to return (optional: 100 by default) |
34
|
|
|
* @param bool|null $subscribed `true` to lists subscribed, `false` for unsubscribed. list all if null |
35
|
|
|
* |
36
|
|
|
* @return IndexResponse |
37
|
|
|
* |
38
|
|
|
* @throws \Exception |
39
|
|
|
*/ |
40
|
3 |
|
public function index(string $address, int $limit = 100, bool $subscribed = null) |
41
|
|
|
{ |
42
|
3 |
|
Assert::stringNotEmpty($address); |
43
|
3 |
|
Assert::greaterThan($limit, 0); |
44
|
|
|
|
45
|
|
|
$params = [ |
46
|
3 |
|
'limit' => $limit, |
47
|
|
|
]; |
48
|
|
|
|
49
|
3 |
|
if (true === $subscribed) { |
50
|
1 |
|
$params['subscribed'] = 'yes'; |
51
|
2 |
|
} elseif (false === $subscribed) { |
52
|
1 |
|
$params['subscribed'] = 'no'; |
53
|
|
|
} |
54
|
|
|
|
55
|
3 |
|
$response = $this->httpGet(sprintf('/v3/lists/%s/members/pages', $address), $params); |
56
|
|
|
|
57
|
3 |
|
return $this->hydrateResponse($response, IndexResponse::class); |
58
|
|
|
} |
59
|
|
|
|
60
|
|
|
/** |
61
|
|
|
* Shows a single member of the mailing list. |
62
|
|
|
* |
63
|
|
|
* @param string $list Address of the mailing list |
64
|
|
|
* @param string $address Address of the member |
65
|
|
|
* |
66
|
|
|
* @return ShowResponse |
67
|
|
|
* |
68
|
|
|
* @throws \Exception |
69
|
|
|
*/ |
70
|
|
|
public function show(string $list, string $address) |
71
|
|
|
{ |
72
|
|
|
Assert::stringNotEmpty($list); |
73
|
|
|
Assert::stringNotEmpty($address); |
74
|
|
|
|
75
|
|
|
$response = $this->httpGet(sprintf('/v3/lists/%s/members/%s', $list, $address)); |
76
|
|
|
|
77
|
|
|
return $this->hydrateResponse($response, ShowResponse::class); |
78
|
|
|
} |
79
|
|
|
|
80
|
|
|
/** |
81
|
|
|
* Creates (or updates) a member of the mailing list. |
82
|
|
|
* |
83
|
|
|
* @param string $list Address of the mailing list |
84
|
|
|
* @param string $address Address for the member |
85
|
|
|
* @param string $name Name for the member (optional) |
86
|
|
|
* @param array $vars Array of field => value pairs to store additional data |
87
|
|
|
* @param bool $subscribed `true` to add as subscribed (default), `false` as unsubscribed |
88
|
|
|
* @param bool $upsert `true` to update member if present, `false` to raise error in case of a duplicate member (default) |
89
|
|
|
* |
90
|
|
|
* @return CreateResponse |
91
|
|
|
* |
92
|
|
|
* @throws \Exception |
93
|
|
|
*/ |
94
|
3 |
|
public function create(string $list, string $address, string $name = null, array $vars = [], bool $subscribed = true, bool $upsert = false) |
95
|
|
|
{ |
96
|
3 |
|
Assert::stringNotEmpty($list); |
97
|
2 |
|
Assert::stringNotEmpty($address); |
98
|
1 |
|
Assert::nullOrStringNotEmpty($name); |
99
|
|
|
|
100
|
|
|
$params = [ |
101
|
1 |
|
'address' => $address, |
102
|
1 |
|
'name' => $name, |
103
|
1 |
|
'vars' => \json_encode($vars), |
104
|
1 |
|
'subscribed' => $subscribed ? 'yes' : 'no', |
105
|
1 |
|
'upsert' => $upsert ? 'yes' : 'no', |
106
|
|
|
]; |
107
|
|
|
|
108
|
1 |
|
$response = $this->httpPost(sprintf('/v3/lists/%s/members', $list), $params); |
109
|
|
|
|
110
|
1 |
|
return $this->hydrateResponse($response, CreateResponse::class); |
111
|
|
|
} |
112
|
|
|
|
113
|
|
|
/** |
114
|
|
|
* Adds multiple members (up to 1000) to the mailing list. |
115
|
|
|
* |
116
|
|
|
* @param string $list Address of the mailing list |
117
|
|
|
* @param array $members Array of members, each item should be either a single string address or an array of member properties |
118
|
|
|
* @param bool $upsert `true` to update existing members, `false` (default) to ignore duplicates |
119
|
|
|
* |
120
|
|
|
* @return UpdateResponse |
121
|
|
|
* |
122
|
|
|
* @throws \Exception |
123
|
|
|
*/ |
124
|
3 |
|
public function createMultiple(string $list, array $members, $upsert = false) |
125
|
|
|
{ |
126
|
3 |
|
Assert::stringNotEmpty($list); |
127
|
3 |
|
Assert::isArray($members); |
128
|
|
|
|
129
|
|
|
// workaround for webmozart/asserts <= 1.2 |
130
|
3 |
|
if (count($members) > 1000) { |
131
|
1 |
|
throw new InvalidArgumentException(sprintf( |
132
|
1 |
|
'Expected an Array to contain at most %2$d elements. Got: %d', |
133
|
1 |
|
1000, |
134
|
1 |
|
count($members) |
135
|
|
|
)); |
136
|
|
|
} |
137
|
|
|
|
138
|
2 |
|
foreach ($members as $data) { |
139
|
2 |
|
if (is_string($data)) { |
140
|
2 |
|
Assert::stringNotEmpty($data); |
141
|
|
|
// single address - no additional validation required |
142
|
2 |
|
continue; |
143
|
|
|
} |
144
|
|
|
|
145
|
2 |
|
Assert::isArray($data); |
146
|
|
|
|
147
|
2 |
View Code Duplication |
foreach ($data as $field => &$value) { |
|
|
|
|
148
|
|
|
switch ($field) { |
149
|
2 |
|
case 'address': |
150
|
2 |
|
Assert::stringNotEmpty($value); |
151
|
|
|
|
152
|
2 |
|
break; |
153
|
2 |
|
case 'vars': |
154
|
|
|
if (is_array($value)) { |
155
|
|
|
$value = json_encode($value); |
156
|
|
|
} |
157
|
|
|
// We should assert that "vars"'s $value is a string. |
158
|
|
|
// no break |
159
|
2 |
|
case 'name': |
160
|
2 |
|
Assert::string($value); |
161
|
|
|
|
162
|
2 |
|
break; |
163
|
2 |
|
case 'subscribed': |
164
|
2 |
|
Assert::oneOf($value, ['yes', 'no']); |
165
|
|
|
|
166
|
2 |
|
break; |
167
|
|
|
} |
168
|
|
|
} |
169
|
|
|
} |
170
|
|
|
|
171
|
|
|
$params = [ |
172
|
1 |
|
'members' => json_encode($members), |
173
|
1 |
|
'upsert' => $upsert ? 'yes' : 'no', |
174
|
|
|
]; |
175
|
|
|
|
176
|
1 |
|
$response = $this->httpPost(sprintf('/v3/lists/%s/members.json', $list), $params); |
177
|
|
|
|
178
|
1 |
|
return $this->hydrateResponse($response, MailingListUpdateResponse::class); |
179
|
|
|
} |
180
|
|
|
|
181
|
|
|
/** |
182
|
|
|
* Updates a member on the mailing list. |
183
|
|
|
* |
184
|
|
|
* @param string $list Address of the mailing list |
185
|
|
|
* @param string $address Address of the member |
186
|
|
|
* @param array $parameters Array of key => value pairs to update |
187
|
|
|
* |
188
|
|
|
* @return UpdateResponse |
189
|
|
|
* |
190
|
|
|
* @throws \Exception |
191
|
|
|
*/ |
192
|
2 |
|
public function update(string $list, string $address, array $parameters = []) |
193
|
|
|
{ |
194
|
2 |
|
Assert::stringNotEmpty($list); |
195
|
2 |
|
Assert::stringNotEmpty($address); |
196
|
2 |
|
Assert::isArray($parameters); |
197
|
|
|
|
198
|
2 |
View Code Duplication |
foreach ($parameters as $field => $value) { |
|
|
|
|
199
|
|
|
switch ($field) { |
200
|
2 |
|
case 'vars': |
201
|
2 |
|
if (is_array($value)) { |
202
|
|
|
$value = json_encode($value); |
203
|
|
|
} |
204
|
|
|
// We should assert that "vars"'s $value is a string. |
205
|
|
|
// no break |
206
|
1 |
|
case 'address': |
207
|
1 |
|
case 'name': |
208
|
2 |
|
Assert::stringNotEmpty($value); |
209
|
|
|
|
210
|
1 |
|
break; |
211
|
1 |
|
case 'subscribed': |
212
|
1 |
|
Assert::oneOf($value, ['yes', 'no']); |
213
|
|
|
|
214
|
1 |
|
break; |
215
|
|
|
} |
216
|
|
|
} |
217
|
|
|
|
218
|
1 |
|
$response = $this->httpPut(sprintf('/v3/lists/%s/members/%s', $list, $address), $parameters); |
219
|
|
|
|
220
|
1 |
|
return $this->hydrateResponse($response, UpdateResponse::class); |
221
|
|
|
} |
222
|
|
|
|
223
|
|
|
/** |
224
|
|
|
* Removes a member from the mailing list. |
225
|
|
|
* |
226
|
|
|
* @param string $list Address of the mailing list |
227
|
|
|
* @param string $address Address of the member |
228
|
|
|
* |
229
|
|
|
* @return DeleteResponse |
230
|
|
|
* |
231
|
|
|
* @throws \Exception |
232
|
|
|
*/ |
233
|
1 |
|
public function delete(string $list, string $address) |
234
|
|
|
{ |
235
|
1 |
|
Assert::stringNotEmpty($list); |
236
|
1 |
|
Assert::stringNotEmpty($address); |
237
|
|
|
|
238
|
1 |
|
$response = $this->httpDelete(sprintf('/v3/lists/%s/members/%s', $list, $address)); |
239
|
|
|
|
240
|
1 |
|
return $this->hydrateResponse($response, DeleteResponse::class); |
241
|
|
|
} |
242
|
|
|
} |
243
|
|
|
|
Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation.
You can also find more detailed suggestions in the “Code” section of your repository.