> ## Documentation Index
> Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP

> Integrate Dodo Payments into your PHP applications with a modern, PSR-4 compliant SDK

The PHP SDK provides a robust and flexible way to integrate Dodo Payments into your PHP applications. Built following modern PHP standards with PSR-4 autoloading, it offers extensive test coverage and detailed documentation.

## Installation

Install the SDK using Composer:

```bash theme={null}
composer require dodopayments/client
```

<Info>
  The SDK requires PHP 8.0 or higher and Composer for dependency management.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```php theme={null}
<?php

use Dodopayments\Client;
use Dodopayments\CheckoutSessions\CheckoutSessionCreateParams\ProductCart;

$client = new Client(
  bearerToken: getenv("DODO_PAYMENTS_API_KEY") ?: "My Bearer Token",
  environment: "test_mode",
);

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [ProductCart::with(productID: "product_id", quantity: 1)]
);

var_dump($checkoutSessionResponse->session_id);
```

<Warning>
  Store your API keys securely using environment variables. Never expose them in your codebase or commit them to version control.
</Warning>

## Core Features

<CardGroup cols={2}>
  <Card title="PSR-4 Compliant" icon="check">
    Follows PHP Standards Recommendations for modern PHP development
  </Card>

  <Card title="Modern PHP" icon="php">
    Built for PHP 8+ with type declarations and strict types
  </Card>

  <Card title="Extensive Testing" icon="vial">
    Comprehensive test coverage for reliability and stability
  </Card>

  <Card title="Exception Handling" icon="shield-check">
    Clear exception types for different error scenarios
  </Card>
</CardGroup>

## Configuration

### Retry Configuration

Configure automatic retry behavior:

```php theme={null}
<?php

use Dodopayments\Client;
use Dodopayments\RequestOptions;
use Dodopayments\CheckoutSessions\CheckoutSessionCreateParams\ProductCart;

// Configure default for all requests
$client = new Client(maxRetries: 0);

// Or, configure per-request
$result = $client->checkoutSessions->create(
  productCart: [ProductCart::with(productID: "product_id", quantity: 0)],
  requestOptions: RequestOptions::with(maxRetries: 5),
);
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```php theme={null}
$session = $client->checkoutSessions->create(
  productCart: [
    ProductCart::with(productID: "prod_123", quantity: 1)
  ],
  returnUrl: "https://yourdomain.com/return"
);

header('Location: ' . $session->url);
```

### Manage Customers

Create and retrieve customer information:

```php theme={null}
// Create a customer
$customer = $client->customers->create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: [
    "user_id" => "12345"
  ]
);

// Retrieve customer
$customer = $client->customers->retrieve("cus_123");
echo "Customer: {$customer->name} ({$customer->email})";
```

### Handle Subscriptions

Create and manage recurring subscriptions:

```php theme={null}
// Create a subscription
$subscription = $client->subscriptions->create(
  customerID: "cus_123",
  productID: "prod_456",
  priceID: "price_789"
);

// Cancel subscription
$client->subscriptions->cancel($subscription->id);
```

## Pagination

Work with paginated list responses:

```php theme={null}
$page = $client->payments->list();

var_dump($page);

// Fetch items from the current page
foreach ($page->getItems() as $item) {
  var_dump($item->brand_id);
}

// Auto-paginate: fetch items from all pages
foreach ($page->pagingEachItem() as $item) {
  var_dump($item->brand_id);
}
```

## Error Handling

Handle various API exceptions:

```php theme={null}
<?php

use Dodopayments\CheckoutSessions\CheckoutSessionCreateParams\ProductCart;
use Dodopayments\Core\Exceptions\APIConnectionException;
use Dodopayments\Core\Exceptions\RateLimitError;
use Dodopayments\Core\Exceptions\APIStatusError;

try {
  $checkoutSessionResponse = $client->checkoutSessions->create(
    productCart: [ProductCart::with(productID: "product_id", quantity: 0)]
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  var_dump($e->getPrevious());
} catch (RateLimitError $_) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusError $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}
```

<Tip>
  Always wrap API calls in try-catch blocks to handle potential errors gracefully and provide meaningful feedback to users.
</Tip>

## Advanced Usage

### Undocumented Endpoints

Make requests to undocumented endpoints:

```php theme={null}
<?php

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);
```

### Undocumented Parameters

Send undocumented parameters:

```php theme={null}
<?php

use Dodopayments\RequestOptions;
use Dodopayments\CheckoutSessions\CheckoutSessionCreateParams\ProductCart;

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [ProductCart::with(productID: "product_id", quantity: 0)],
  requestOptions: RequestOptions::with(
    extraQueryParams: ["my_query_parameter" => "value"],
    extraBodyParams: ["my_body_parameter" => "value"],
    extraHeaders: ["my-header" => "value"],
  ),
);

var_dump($checkoutSessionResponse["my_undocumented_property"]);
```

## Framework Integration

### Laravel

Create a service for Laravel applications:

```php theme={null}
<?php

namespace App\Services;

use Dodopayments\Client;

class PaymentService
{
    protected $client;

    public function __construct()
    {
        $this->client = new Client(
            bearerToken: config('services.dodo.api_key')
        );
    }

    public function createCheckout(array $items)
    {
        return $this->client->checkoutSessions->create(
            productCart: $items,
            returnUrl: route('checkout.return')
        );
    }
}
```

Add configuration in `config/services.php`:

```php theme={null}
'dodo' => [
    'api_key' => env('DODO_API_KEY'),
    'environment' => env('DODO_ENVIRONMENT', 'sandbox')
],
```

### Symfony

Create a service in Symfony:

```php theme={null}
<?php

namespace App\Service;

use Dodopayments\Client;

class DodoPaymentService
{
    private Client $client;

    public function __construct(string $apiKey)
    {
        $this->client = new Client(bearerToken: $apiKey);
    }

    public function createPayment(int $amount, string $currency, string $customerId): object
    {
        return $this->client->payments->create(
            amount: $amount,
            currency: $currency,
            customerID: $customerId
        );
    }
}
```

Register in `config/services.yaml`:

```yaml theme={null}
services:
    App\Service\DodoPaymentService:
        arguments:
            $apiKey: '%env(DODO_API_KEY)%'
```

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-php">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-php/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the PHP SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-php)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-php/blob/main/CONTRIBUTING.md) to get started.