Square PHP SDK

https://github.com/square/square-php-sdk
Admin
The Square PHP library provides convenient access to the Square API from PHP, simplifying payment...
Tokens:2,417
Snippets:17
Trust Score:9.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Square PHP SDK

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Installs the Square PHP SDK using Composer. This is the primary method for adding the SDK to your PHP project.

```shell
composer require square/square
```

--------------------------------

### Handle Square API Exceptions

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Provides an example of how to catch and handle `SquareApiException` when the API returns an error status code.

```php
use Square\Exceptions\SquareApiException;
use Square\Exceptions\SquareException;

try {
    $square->payments->create(...);
} catch (SquareApiException $e) {
    echo 'Square API Exception occurred: ' . $e->getMessage() . "\n";
    echo 'Status Code: ' . $e->getCode() . "\n";
    echo 'Response Body: ' . $e->getBody() . "\n";
    // Optionally, rethrow the exception or handle accordingly.
}
```

--------------------------------

### PHPDoc Annotation for Enum Type

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Provides an example of a PHPDoc annotation for specifying an enum type, ensuring type safety for parameters.

```php
/**
 * @param ?value-of<InvoiceRequestType> $requestType Optional request type for the invoice.
 */
```

--------------------------------

### Instantiate SquareClient using Environment Variable

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Demonstrates instantiating the SquareClient without a token, relying on the SQUARE_TOKEN environment variable for authentication.

```php
use Square\SquareClient;

$square = new SquareClient(); // Token is read from the SQUARE_TOKEN environment variable.
```

--------------------------------

### Create Payment with Square PHP SDK

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Demonstrates how to create a payment using the Square PHP SDK. It includes setting idempotency key, source ID, amount, tip, and cash details.

```php
use Square\SquareClient;
use Square\Payments\Requests\CreatePaymentRequest;
use Square\Types\CashPaymentDetails;
use Square\Types\Currency;
use Square\Types\Money;

$square = new SquareClient();
$response = $square->payments->create(
    request: new CreatePaymentRequest(
        [
            'idempotencyKey' => '4935a656-a929-4792-b97c-8848be85c27c',
            'sourceId' => 'CASH',
            'amountMoney' => new Money([
                'amount' => 100,
                'currency' => Currency::Usd->value
            ]),
            'tipMoney' => new Money([
                'amount' => 50,
                'currency' => Currency::Usd->value
            ]),
            'cashDetails' => new CashPaymentDetails([
                'buyerSuppliedMoney' => new Money([
                    'amount' => 200,
                    'currency' => Currency::Usd->value
                ])
            ]),
        ],
    )
);
```

--------------------------------

### Use Legacy and New SDK Together in PHP

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Demonstrates how to use both the legacy and the new Square PHP SDKs within the same file. This facilitates a gradual migration from the older version to the improved SDK.

```php
use Square\SquareClient;
use Square\Legacy\SquareClient as LegacySquareClient;

$square = new SquareClient();
$legacyClient = new LegacySquareClient();
```

--------------------------------

### Instantiate SquareClient with Token

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Shows how to instantiate the SquareClient class with a provided Square API token.

```php
use Square\SquareClient;

$square = new SquareClient("SQUARE_TOKEN");
```

--------------------------------

### Configure SquareClient with Production Environment

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Configures the SquareClient to use the production environment for API requests.

```php
use Square\SquareClient;
use Square\Environments;

$square = new SquareClient(options: [
  'baseUrl' => Environments::Production->value // Used by default
]);
```

--------------------------------

### Configure SquareClient with Custom URL

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Shows how to configure the SquareClient to use a custom base URL for API requests, useful for staging or specific environments.

```php
use Square\SquareClient;

$square = new SquareClient(options: [
  'baseUrl' => 'https://custom-staging.com'
]);
```

--------------------------------

### Configure Custom HTTP Client in PHP

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Shows how to integrate a custom HTTP client, specifically a Guzzle client with custom configurations like timeouts, with the Square PHP SDK. This allows for more control over HTTP requests.

```php
use GuzzleHttp\Client;
use Square\SquareClient;

// Create a custom Guzzle client with specific configuration.
$client = new Client([
    'timeout' => 5.0,
]);

// Pass the custom client when creating an instance of the class.
$square = new SquareClient(options: [
    'client' => $client
]);
```

--------------------------------

### Iterate Through Paginated Pages

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Shows how to iterate through each page of a paginated list response, accessing items within each page.

```php
foreach ($payments->getPages() as $page) {
    foreach ($page->getItems() as $payment) {
        echo sprintf(
            "payment: ID: %s Created at: %s, Updated at: %s\n",
            $payment->getId(),
            $payment->getCreatedAt(),
            $payment->getUpdatedAt(),
        );
    }
}
```

--------------------------------

### Iterate Through Paginated List Results

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Demonstrates how to automatically iterate through all items in a paginated list response from the Square API.

```php
use Square\Payments\Requests\ListPaymentsRequest;

$payments = $square->payments->list(
    new ListPaymentsRequest([
        'total' => 100,
    ]),
);

foreach ($payments as $payment) {
    echo sprintf(
        "payment: ID: %s Created at: %s, Updated at: %s\n",
        $payment->getId(),
        $payment->getCreatedAt(),
        $payment->getUpdatedAt(),
    );
}
```

--------------------------------

### Set Request Timeout in Square PHP SDK

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Demonstrates how to set a timeout for an individual API request using the 'timeout' option.

```php
$payments = $square->payments->list(
    request: new ListPaymentsRequest([
        'total' => 100,
    ]),
    options: [
        'timeout' = 1.0,
    ],
);
```

--------------------------------

### Send Additional Properties in PHP Request

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Illustrates how to send additional, non-standard query parameters or request body properties with the Square PHP SDK. This is useful for accessing unreleased or hidden API features.

```php
use Square\TeamMembers\Requests\SearchTeamMembersRequest;

$teamMembers = $square->teamMembers->search(
    request: new SearchTeamMembersRequest([
        'limit' => 100,
    ]),
    options: [
        'queryParameters' => [
            'status' => 'DEACTIVATED'
        ],
    ],
);
```

--------------------------------

### Receive Additional Properties in PHP Response

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Explains how to access any additional properties present in the API response that are not explicitly defined in the SDK's response classes. This is achieved using the `getAdditionalProperties` method.

```php
$payments = $square->payments->create(...);
$additionalProperties = $payments->getAdditionalProperties();
```

--------------------------------

### Use PHP Enums for Square SDK Types

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Illustrates the usage of PHP 8.1 enums within the Square SDK for type safety, specifically for request types.

```php
use Square\Types\InvoicePaymentRequest;
use Square\Types\InvoiceRequestType;

$paymentRequest = new InvoicePaymentRequest([
    'requestType' => InvoiceRequestType::Balance->value,
    ...
]);
```

--------------------------------

### Verify Webhook Signature in PHP

Source: https://github.com/square/square-php-sdk/blob/master/README.md

Verifies the signature of incoming webhook events to ensure authenticity. It requires the request body, signature header, a signature key, and the notification URL.

```php
use Square\Utils\WebhooksHelper;

$isValid = WebhooksHelper::verifySignature(
    requestBody: $requestBody,
    signatureHeader: $headers['x-square-hmacsha256-signature'],
    signatureKey: 'YOUR_SIGNATURE_KEY',
    notificationUrl: 'https://example.com/webhook' // The URL where event notifications are sent.
);
```
Tokens:
Raw