PluginProbe
Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) / 1.8.13
Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) v1.8.13
1.8.13 1.8.12.3 1.8.12.2 1.8.12.1 1.8.12 1.8.11.3 1.8.11.2 1.8.11.1 1.8.11 1.6.6 1.6.60 1.6.7 1.6.8 1.6.9 1.7.0 1.7.0.1 1.7.0.11 1.7.0.12 1.7.0.14 1.7.0.2 1.7.0.3 1.7.0.5 1.7.0.6 1.7.0.7 1.7.0.9 All 211 releases
charitable / vendor / square / square / src / Merchants / CustomAttributes / CustomAttributesClient.php

CustomAttributesClient.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at vendor/square/square/src/Merchants/CustomAttributes/CustomAttributesClient.php

483 lines 20.7 KB
No matching file
Up and down to move Enter to open Esc to close
Raw Download Zip
1 <?php
2
3 namespace Square\Merchants\CustomAttributes;
4
5 use GuzzleHttp\ClientInterface;
6 use Square\Core\Client\RawClient;
7 use Square\Merchants\CustomAttributes\Requests\BulkDeleteMerchantCustomAttributesRequest;
8 use Square\Types\BulkDeleteMerchantCustomAttributesResponse;
9 use Square\Exceptions\SquareException;
10 use Square\Exceptions\SquareApiException;
11 use Square\Core\Json\JsonApiRequest;
12 use Square\Environments;
13 use Square\Core\Client\HttpMethod;
14 use JsonException;
15 use GuzzleHttp\Exception\RequestException;
16 use Psr\Http\Client\ClientExceptionInterface;
17 use Square\Merchants\CustomAttributes\Requests\BulkUpsertMerchantCustomAttributesRequest;
18 use Square\Types\BulkUpsertMerchantCustomAttributesResponse;
19 use Square\Merchants\CustomAttributes\Requests\ListCustomAttributesRequest;
20 use Square\Core\Pagination\Pager;
21 use Square\Types\CustomAttribute;
22 use Square\Core\Pagination\CursorPager;
23 use Square\Types\ListMerchantCustomAttributesResponse;
24 use Square\Merchants\CustomAttributes\Requests\GetCustomAttributesRequest;
25 use Square\Types\RetrieveMerchantCustomAttributeResponse;
26 use Square\Merchants\CustomAttributes\Requests\UpsertMerchantCustomAttributeRequest;
27 use Square\Types\UpsertMerchantCustomAttributeResponse;
28 use Square\Merchants\CustomAttributes\Requests\DeleteCustomAttributesRequest;
29 use Square\Types\DeleteMerchantCustomAttributeResponse;
30
31 class CustomAttributesClient
32 {
33 /**
34 * @var array{
35 * baseUrl?: string,
36 * client?: ClientInterface,
37 * maxRetries?: int,
38 * timeout?: float,
39 * headers?: array<string, string>,
40 * } $options
41 */
42 private array $options;
43
44 /**
45 * @var RawClient $client
46 */
47 private RawClient $client;
48
49 /**
50 * @param RawClient $client
51 * @param ?array{
52 * baseUrl?: string,
53 * client?: ClientInterface,
54 * maxRetries?: int,
55 * timeout?: float,
56 * headers?: array<string, string>,
57 * } $options
58 */
59 public function __construct(
60 RawClient $client,
61 ?array $options = null,
62 ) {
63 $this->client = $client;
64 $this->options = $options ?? [];
65 }
66
67 /**
68 * Deletes [custom attributes](entity:CustomAttribute) for a merchant as a bulk operation.
69 * To delete a custom attribute owned by another application, the `visibility` setting must be
70 * `VISIBILITY_READ_WRITE_VALUES`.
71 *
72 * @param BulkDeleteMerchantCustomAttributesRequest $request
73 * @param ?array{
74 * baseUrl?: string,
75 * maxRetries?: int,
76 * timeout?: float,
77 * headers?: array<string, string>,
78 * queryParameters?: array<string, mixed>,
79 * bodyProperties?: array<string, mixed>,
80 * } $options
81 * @return BulkDeleteMerchantCustomAttributesResponse
82 * @throws SquareException
83 * @throws SquareApiException
84 */
85 public function batchDelete(BulkDeleteMerchantCustomAttributesRequest $request, ?array $options = null): BulkDeleteMerchantCustomAttributesResponse
86 {
87 $options = array_merge($this->options, $options ?? []);
88 try {
89 $response = $this->client->sendRequest(
90 new JsonApiRequest(
91 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
92 path: "v2/merchants/custom-attributes/bulk-delete",
93 method: HttpMethod::POST,
94 body: $request,
95 ),
96 $options,
97 );
98 $statusCode = $response->getStatusCode();
99 if ($statusCode >= 200 && $statusCode < 400) {
100 $json = $response->getBody()->getContents();
101 return BulkDeleteMerchantCustomAttributesResponse::fromJson($json);
102 }
103 } catch (JsonException $e) {
104 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
105 } catch (RequestException $e) {
106 $response = $e->getResponse();
107 if ($response === null) {
108 throw new SquareException(message: $e->getMessage(), previous: $e);
109 }
110 throw new SquareApiException(
111 message: "API request failed",
112 statusCode: $response->getStatusCode(),
113 body: $response->getBody()->getContents(),
114 );
115 } catch (ClientExceptionInterface $e) {
116 throw new SquareException(message: $e->getMessage(), previous: $e);
117 }
118 throw new SquareApiException(
119 message: 'API request failed',
120 statusCode: $statusCode,
121 body: $response->getBody()->getContents(),
122 );
123 }
124
125 /**
126 * Creates or updates [custom attributes](entity:CustomAttribute) for a merchant as a bulk operation.
127 * Use this endpoint to set the value of one or more custom attributes for a merchant.
128 * A custom attribute is based on a custom attribute definition in a Square seller account, which is
129 * created using the [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition) endpoint.
130 * This `BulkUpsertMerchantCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert
131 * requests and returns a map of individual upsert responses. Each upsert request has a unique ID
132 * and provides a merchant ID and custom attribute. Each upsert response is returned with the ID
133 * of the corresponding request.
134 * To create or update a custom attribute owned by another application, the `visibility` setting
135 * must be `VISIBILITY_READ_WRITE_VALUES`.
136 *
137 * @param BulkUpsertMerchantCustomAttributesRequest $request
138 * @param ?array{
139 * baseUrl?: string,
140 * maxRetries?: int,
141 * timeout?: float,
142 * headers?: array<string, string>,
143 * queryParameters?: array<string, mixed>,
144 * bodyProperties?: array<string, mixed>,
145 * } $options
146 * @return BulkUpsertMerchantCustomAttributesResponse
147 * @throws SquareException
148 * @throws SquareApiException
149 */
150 public function batchUpsert(BulkUpsertMerchantCustomAttributesRequest $request, ?array $options = null): BulkUpsertMerchantCustomAttributesResponse
151 {
152 $options = array_merge($this->options, $options ?? []);
153 try {
154 $response = $this->client->sendRequest(
155 new JsonApiRequest(
156 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
157 path: "v2/merchants/custom-attributes/bulk-upsert",
158 method: HttpMethod::POST,
159 body: $request,
160 ),
161 $options,
162 );
163 $statusCode = $response->getStatusCode();
164 if ($statusCode >= 200 && $statusCode < 400) {
165 $json = $response->getBody()->getContents();
166 return BulkUpsertMerchantCustomAttributesResponse::fromJson($json);
167 }
168 } catch (JsonException $e) {
169 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
170 } catch (RequestException $e) {
171 $response = $e->getResponse();
172 if ($response === null) {
173 throw new SquareException(message: $e->getMessage(), previous: $e);
174 }
175 throw new SquareApiException(
176 message: "API request failed",
177 statusCode: $response->getStatusCode(),
178 body: $response->getBody()->getContents(),
179 );
180 } catch (ClientExceptionInterface $e) {
181 throw new SquareException(message: $e->getMessage(), previous: $e);
182 }
183 throw new SquareApiException(
184 message: 'API request failed',
185 statusCode: $statusCode,
186 body: $response->getBody()->getContents(),
187 );
188 }
189
190 /**
191 * Lists the [custom attributes](entity:CustomAttribute) associated with a merchant.
192 * You can use the `with_definitions` query parameter to also retrieve custom attribute definitions
193 * in the same call.
194 * When all response pages are retrieved, the results include all custom attributes that are
195 * visible to the requesting application, including those that are owned by other applications
196 * and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
197 *
198 * @param ListCustomAttributesRequest $request
199 * @param ?array{
200 * baseUrl?: string,
201 * maxRetries?: int,
202 * timeout?: float,
203 * headers?: array<string, string>,
204 * queryParameters?: array<string, mixed>,
205 * bodyProperties?: array<string, mixed>,
206 * } $options
207 * @return Pager<CustomAttribute>
208 */
209 public function list(ListCustomAttributesRequest $request, ?array $options = null): Pager
210 {
211 return new CursorPager(
212 request: $request,
213 getNextPage: fn (ListCustomAttributesRequest $request) => $this->_list($request, $options),
214 setCursor: function (ListCustomAttributesRequest $request, ?string $cursor) {
215 $request->setCursor($cursor);
216 },
217 /* @phpstan-ignore-next-line */
218 getNextCursor: fn (ListMerchantCustomAttributesResponse $response) => $response?->getCursor() ?? null,
219 /* @phpstan-ignore-next-line */
220 getItems: fn (ListMerchantCustomAttributesResponse $response) => $response?->getCustomAttributes() ?? [],
221 );
222 }
223
224 /**
225 * Retrieves a [custom attribute](entity:CustomAttribute) associated with a merchant.
226 * You can use the `with_definition` query parameter to also retrieve the custom attribute definition
227 * in the same call.
228 * To retrieve a custom attribute owned by another application, the `visibility` setting must be
229 * `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
230 *
231 * @param GetCustomAttributesRequest $request
232 * @param ?array{
233 * baseUrl?: string,
234 * maxRetries?: int,
235 * timeout?: float,
236 * headers?: array<string, string>,
237 * queryParameters?: array<string, mixed>,
238 * bodyProperties?: array<string, mixed>,
239 * } $options
240 * @return RetrieveMerchantCustomAttributeResponse
241 * @throws SquareException
242 * @throws SquareApiException
243 */
244 public function get(GetCustomAttributesRequest $request, ?array $options = null): RetrieveMerchantCustomAttributeResponse
245 {
246 $options = array_merge($this->options, $options ?? []);
247 $query = [];
248 if ($request->getWithDefinition() != null) {
249 $query['with_definition'] = $request->getWithDefinition();
250 }
251 if ($request->getVersion() != null) {
252 $query['version'] = $request->getVersion();
253 }
254 try {
255 $response = $this->client->sendRequest(
256 new JsonApiRequest(
257 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
258 path: "v2/merchants/{$request->getMerchantId()}/custom-attributes/{$request->getKey()}",
259 method: HttpMethod::GET,
260 query: $query,
261 ),
262 $options,
263 );
264 $statusCode = $response->getStatusCode();
265 if ($statusCode >= 200 && $statusCode < 400) {
266 $json = $response->getBody()->getContents();
267 return RetrieveMerchantCustomAttributeResponse::fromJson($json);
268 }
269 } catch (JsonException $e) {
270 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
271 } catch (RequestException $e) {
272 $response = $e->getResponse();
273 if ($response === null) {
274 throw new SquareException(message: $e->getMessage(), previous: $e);
275 }
276 throw new SquareApiException(
277 message: "API request failed",
278 statusCode: $response->getStatusCode(),
279 body: $response->getBody()->getContents(),
280 );
281 } catch (ClientExceptionInterface $e) {
282 throw new SquareException(message: $e->getMessage(), previous: $e);
283 }
284 throw new SquareApiException(
285 message: 'API request failed',
286 statusCode: $statusCode,
287 body: $response->getBody()->getContents(),
288 );
289 }
290
291 /**
292 * Creates or updates a [custom attribute](entity:CustomAttribute) for a merchant.
293 * Use this endpoint to set the value of a custom attribute for a specified merchant.
294 * A custom attribute is based on a custom attribute definition in a Square seller account, which
295 * is created using the [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition) endpoint.
296 * To create or update a custom attribute owned by another application, the `visibility` setting
297 * must be `VISIBILITY_READ_WRITE_VALUES`.
298 *
299 * @param UpsertMerchantCustomAttributeRequest $request
300 * @param ?array{
301 * baseUrl?: string,
302 * maxRetries?: int,
303 * timeout?: float,
304 * headers?: array<string, string>,
305 * queryParameters?: array<string, mixed>,
306 * bodyProperties?: array<string, mixed>,
307 * } $options
308 * @return UpsertMerchantCustomAttributeResponse
309 * @throws SquareException
310 * @throws SquareApiException
311 */
312 public function upsert(UpsertMerchantCustomAttributeRequest $request, ?array $options = null): UpsertMerchantCustomAttributeResponse
313 {
314 $options = array_merge($this->options, $options ?? []);
315 try {
316 $response = $this->client->sendRequest(
317 new JsonApiRequest(
318 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
319 path: "v2/merchants/{$request->getMerchantId()}/custom-attributes/{$request->getKey()}",
320 method: HttpMethod::POST,
321 body: $request,
322 ),
323 $options,
324 );
325 $statusCode = $response->getStatusCode();
326 if ($statusCode >= 200 && $statusCode < 400) {
327 $json = $response->getBody()->getContents();
328 return UpsertMerchantCustomAttributeResponse::fromJson($json);
329 }
330 } catch (JsonException $e) {
331 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
332 } catch (RequestException $e) {
333 $response = $e->getResponse();
334 if ($response === null) {
335 throw new SquareException(message: $e->getMessage(), previous: $e);
336 }
337 throw new SquareApiException(
338 message: "API request failed",
339 statusCode: $response->getStatusCode(),
340 body: $response->getBody()->getContents(),
341 );
342 } catch (ClientExceptionInterface $e) {
343 throw new SquareException(message: $e->getMessage(), previous: $e);
344 }
345 throw new SquareApiException(
346 message: 'API request failed',
347 statusCode: $statusCode,
348 body: $response->getBody()->getContents(),
349 );
350 }
351
352 /**
353 * Deletes a [custom attribute](entity:CustomAttribute) associated with a merchant.
354 * To delete a custom attribute owned by another application, the `visibility` setting must be
355 * `VISIBILITY_READ_WRITE_VALUES`.
356 *
357 * @param DeleteCustomAttributesRequest $request
358 * @param ?array{
359 * baseUrl?: string,
360 * maxRetries?: int,
361 * timeout?: float,
362 * headers?: array<string, string>,
363 * queryParameters?: array<string, mixed>,
364 * bodyProperties?: array<string, mixed>,
365 * } $options
366 * @return DeleteMerchantCustomAttributeResponse
367 * @throws SquareException
368 * @throws SquareApiException
369 */
370 public function delete(DeleteCustomAttributesRequest $request, ?array $options = null): DeleteMerchantCustomAttributeResponse
371 {
372 $options = array_merge($this->options, $options ?? []);
373 try {
374 $response = $this->client->sendRequest(
375 new JsonApiRequest(
376 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
377 path: "v2/merchants/{$request->getMerchantId()}/custom-attributes/{$request->getKey()}",
378 method: HttpMethod::DELETE,
379 ),
380 $options,
381 );
382 $statusCode = $response->getStatusCode();
383 if ($statusCode >= 200 && $statusCode < 400) {
384 $json = $response->getBody()->getContents();
385 return DeleteMerchantCustomAttributeResponse::fromJson($json);
386 }
387 } catch (JsonException $e) {
388 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
389 } catch (RequestException $e) {
390 $response = $e->getResponse();
391 if ($response === null) {
392 throw new SquareException(message: $e->getMessage(), previous: $e);
393 }
394 throw new SquareApiException(
395 message: "API request failed",
396 statusCode: $response->getStatusCode(),
397 body: $response->getBody()->getContents(),
398 );
399 } catch (ClientExceptionInterface $e) {
400 throw new SquareException(message: $e->getMessage(), previous: $e);
401 }
402 throw new SquareApiException(
403 message: 'API request failed',
404 statusCode: $statusCode,
405 body: $response->getBody()->getContents(),
406 );
407 }
408
409 /**
410 * Lists the [custom attributes](entity:CustomAttribute) associated with a merchant.
411 * You can use the `with_definitions` query parameter to also retrieve custom attribute definitions
412 * in the same call.
413 * When all response pages are retrieved, the results include all custom attributes that are
414 * visible to the requesting application, including those that are owned by other applications
415 * and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
416 *
417 * @param ListCustomAttributesRequest $request
418 * @param ?array{
419 * baseUrl?: string,
420 * maxRetries?: int,
421 * timeout?: float,
422 * headers?: array<string, string>,
423 * queryParameters?: array<string, mixed>,
424 * bodyProperties?: array<string, mixed>,
425 * } $options
426 * @return ListMerchantCustomAttributesResponse
427 * @throws SquareException
428 * @throws SquareApiException
429 */
430 private function _list(ListCustomAttributesRequest $request, ?array $options = null): ListMerchantCustomAttributesResponse
431 {
432 $options = array_merge($this->options, $options ?? []);
433 $query = [];
434 if ($request->getVisibilityFilter() != null) {
435 $query['visibility_filter'] = $request->getVisibilityFilter();
436 }
437 if ($request->getLimit() != null) {
438 $query['limit'] = $request->getLimit();
439 }
440 if ($request->getCursor() != null) {
441 $query['cursor'] = $request->getCursor();
442 }
443 if ($request->getWithDefinitions() != null) {
444 $query['with_definitions'] = $request->getWithDefinitions();
445 }
446 try {
447 $response = $this->client->sendRequest(
448 new JsonApiRequest(
449 baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
450 path: "v2/merchants/{$request->getMerchantId()}/custom-attributes",
451 method: HttpMethod::GET,
452 query: $query,
453 ),
454 $options,
455 );
456 $statusCode = $response->getStatusCode();
457 if ($statusCode >= 200 && $statusCode < 400) {
458 $json = $response->getBody()->getContents();
459 return ListMerchantCustomAttributesResponse::fromJson($json);
460 }
461 } catch (JsonException $e) {
462 throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
463 } catch (RequestException $e) {
464 $response = $e->getResponse();
465 if ($response === null) {
466 throw new SquareException(message: $e->getMessage(), previous: $e);
467 }
468 throw new SquareApiException(
469 message: "API request failed",
470 statusCode: $response->getStatusCode(),
471 body: $response->getBody()->getContents(),
472 );
473 } catch (ClientExceptionInterface $e) {
474 throw new SquareException(message: $e->getMessage(), previous: $e);
475 }
476 throw new SquareApiException(
477 message: 'API request failed',
478 statusCode: $statusCode,
479 body: $response->getBody()->getContents(),
480 );
481 }
482 }
483