charitable / vendor / square / square / README.md

README.md in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at vendor/square/square/README.md

303 lines 8.5 KB

Raw Download Zip

1	# Square PHP SDK
2
3	[](https://github.com/fern-api/fern![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-SDK%20generated%20by%20Fern-brightgreen)](https://github.com/fern-api/fern](https://github.com/fern-api/fern)
4	[](https://packagist.org/packages/square/square![php shield](https://img.shields.io/badge/php-packagist-pink)](https://packagist.org/packages/square/square](https://packagist.org/packages/square/square)
5
6	The Square PHP library provides convenient access to the Square API from PHP.
7
8	## Requirements
9
10	Use of the Square PHP SDK requires:
11	* PHP ^8.1
12
13	## Installation
14
15	Use Composer to configure and install to configure and install the Square PHP SDK:
16
17	```shell
18	composer require square/square
19	```
20
21	## Usage
22
23	```php
24	use Square\SquareClient;
25	use Square\Payments\Requests\CreatePaymentRequest;
26	use Square\Types\CashPaymentDetails;
27	use Square\Types\Currency;
28	use Square\Types\Money;
29
30	$square = new SquareClient();
31	$response = $square->payments->create(
32	request: new CreatePaymentRequest(
33	[
34	'idempotencyKey' => '4935a656-a929-4792-b97c-8848be85c27c',
35	'sourceId' => 'CASH',
36	'amountMoney' => new Money([
37	'amount' => 100,
38	'currency' => Currency::Usd->value
39	]),
40	'tipMoney' => new Money([
41	'amount' => 50,
42	'currency' => Currency::Usd->value
43	]),
44	'cashDetails' => new CashPaymentDetails([
45	'buyerSuppliedMoney' => new Money([
46	'amount' => 200,
47	'currency' => Currency::Usd->value
48	])
49	]),
50	],
51	)
52	);
53	```
54
55	## Instantiation
56
57	To get started with the Square SDK, instantiate the `SquareClient` class as follows:
58
59	```php
60	use Square\SquareClient;
61
62	$square = new SquareClient("SQUARE_TOKEN");
63	```
64
65	Alternatively, you can omit the token when constructing the client.
66	In this case, the SDK will automatically read the token from the
67	`SQUARE_TOKEN` environment variable:
68
69	```php
70	use Square\SquareClient;
71
72	$square = new SquareClient(); // Token is read from the SQUARE_TOKEN environment variable.
73	```
74
75	### Environment and Custom URLs
76
77	This SDK allows you to configure different environments or custom URLs for API requests.
78	You can either use the predefined environments or specify your own custom URL.
79
80	#### Environments
81
82	```php
83	use Square\SquareClient;
84	use Square\Environments;
85
86	$square = new SquareClient(options: [
87	'baseUrl' => Environments::Production->value // Used by default
88	]);
89	```
90
91	#### Custom URL
92
93	```php
94	use Square\SquareClient;
95
96	$square = new SquareClient(options: [
97	'baseUrl' => 'https://custom-staging.com'
98	]);
99	```
100
101	## Enums
102
103	This SDK leverages PHP 8.1’s first-class enums to improve type safety and usability. In order to maintain forward
104	compatibility with the API —- where new enum values may be introduced in the future -— we define enum properties
105	as `string` and use `value-of` annotations to specify the corresponding enum type.
106
107	### Example Usage
108	```php
109	use Square\Types\InvoicePaymentRequest;
110	use Square\Types\InvoiceRequestType;
111
112	$paymentRequest = new InvoicePaymentRequest([
113	'requestType' => InvoiceRequestType::Balance->value,
114	...
115	]);
116	```
117
118	### PHPDoc Annotations
119	```php
120	/**
121	* @param ?value-of<InvoiceRequestType> $requestType Optional request type for the invoice.
122	*/
123	```
124
125	## Automatic Pagination
126
127	List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:
128
129	```php
130	use Square\Payments\Requests\ListPaymentsRequest;
131
132	$payments = $square->payments->list(
133	new ListPaymentsRequest([
134	'total' => 100,
135	]),
136	);
137
138	foreach ($payments as $payment) {
139	echo sprintf(
140	"payment: ID: %s Created at: %s, Updated at: %s\n",
141	$payment->getId(),
142	$payment->getCreatedAt(),
143	$payment->getUpdatedAt(),
144	);
145	}
146	```
147
148	You can also iterate page-by-page:
149
150	```php
151	foreach ($payments->getPages() as $page) {
152	foreach ($page->getItems() as $payment) {
153	echo sprintf(
154	"payment: ID: %s Created at: %s, Updated at: %s\n",
155	$payment->getId(),
156	$payment->getCreatedAt(),
157	$payment->getUpdatedAt(),
158	);
159	}
160	}
161	```
162
163	## Timeouts
164
165	Setting a timeout for each individual request is as simple as using the `timeout` request option. Setting a one second
166	timeout for an individual API call looks like the following:
167
168	```php
169	$payments = $square->payments->list(
170	request: new ListPaymentsRequest([
171	'total' => 100,
172	]),
173	options: [
174	'timeout' = 1.0,
175	],
176	);
177	```
178
179	## Exception Handling
180
181	When the API returns a non-zero status code, (`4xx` or `5xx` response), a `SquareApiException` will be thrown:
182	```php
183	use Square\Exceptions\SquareApiException;
184	use Square\Exceptions\SquareException;
185
186	try {
187	$square->payments->create(...);
188	} catch (SquareApiException $e) {
189	echo 'Square API Exception occurred: ' . $e->getMessage() . "\n";
190	echo 'Status Code: ' . $e->getCode() . "\n";
191	echo 'Response Body: ' . $e->getBody() . "\n";
192	// Optionally, rethrow the exception or handle accordingly.
193	}
194	```
195
196	## Webhook Signature Verification
197
198	The SDK provides utility methods that allow you to verify webhook signatures and ensure
199	that all webhook events originate from Square. The `WebhooksHelper.verifySignature` method
200	can be used to verify the signature like so:
201
202	```php
203	use Square\Utils\WebhooksHelper;
204
205	$isValid = WebhooksHelper.verifySignature(
206	requestBody: $requestBody,
207	signatureHeader: $headers['x-square-hmacsha256-signature'],
208	signatureKey: 'YOUR_SIGNATURE_KEY',
209	notificationUrl: 'https://example.com/webhook', // The URL where event notifications are sent.
210	)
211	```
212
213	## Legacy SDK
214
215	While the new SDK has a lot of improvements, we at Square understand that it takes time to upgrade when there are breaking changes.
216	To make the migration easier, the new SDK also exports the legacy SDK as `Square\Legacy\...`. Here's an example of how you can use the
217	legacy SDK alongside the new SDK inside a single file:
218
219	```php
220	use Square\SquareClient;
221	use Square\Legacy\SquareClient as LegacySquareClient;
222
223	$square = new SquareClient();
224	$legacyClient = new LegacySquareClient();
225	```
226
227	We recommend migrating to the new SDK using the following steps:
228
229	1. Upgrade the package to `^41.0.0`
230	2. Search and replace all requires and imports from `Square\...` to `Square\Legacy\...`
231
232	3. Gradually move over to use the new SDK by importing it from the `Square\...` import.
233
234	## Advanced
235
236	### Custom HTTP Client
237
238	This SDK is built to work with any HTTP client that implements Guzzle’s `ClientInterface`. By default, if no client
239	is provided, the SDK will use Guzzle’s default HTTP client. However, you can pass your own client that adheres to
240	`ClientInterface`:
241
242	```php
243	use GuzzleHttp\Client;
244	use Square\SquareClient;
245
246	// Create a custom Guzzle client with specific configuration.
247	$client = new Client([
248	'timeout' => 5.0,
249	]);
250
251	// Pass the custom client when creating an instance of the class.
252	$square = new SquareClient(options: [
253	'client' => $client
254	]);
255	```
256
257	### Send Additional Properties
258
259	All endpoints support sending additional request body properties and query parameters that are not already supported by
260	the SDK. This is useful whenever you need to interact with an unreleased or hidden feature.
261
262	For example, suppose that a new feature was rolled out that allowed users to list all deactivated team members. You could
263	set the relevant query parameters like so:
264
265	```php
266	use Square\TeamMembers\Requests\SearchTeamMembersRequest;
267
268	$teamMembers = $square->teamMembers->search(
269	request: new SearchTeamMembersRequest([
270	'limit' => 100,
271	]),
272	options: [
273	'queryParameters' = [
274	'status' => 'DEACTIVATED'
275	],
276	],
277	);
278	```
279
280	### Receive Additional Properties
281
282	Every response type includes the `getAdditionalProperties` method, which returns an `array` that contains any properties in the
283	JSON response that were not specified in the returned class. Similar to the use case for sending additional parameters, this can
284	be useful for API features not present in the SDK yet.
285
286	You can access the additional properties like so:
287
288	```php
289	$payments = $square->payments->create(...);
290	$additionalProperties = $payments->getAdditionalProperties();
291	```
292
293	## Contributing
294
295	While we value open-source contributions to this SDK, this library
296	is generated programmatically. Additions made directly to this library
297	would have to be moved over to our generation code, otherwise they would
298	be overwritten upon the next generated release. Feel free to open a PR as a
299	proof of concept, but know that we will not be able to merge it as-is.
300	We suggest opening an issue first to discuss with us!
301
302	On the other hand, contributions to the README are always very welcome!
303