From 9e9e06fdb360f1a42ded040073a4363754bbab5e Mon Sep 17 00:00:00 2001 From: courier-docs-bot Date: Fri, 20 Feb 2026 18:11:11 +0000 Subject: [PATCH] docs: sync README from mintlify-docs (2026-02-20 18:11 UTC) --- README.md | 176 ++++++------------------------------------------------ 1 file changed, 19 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index 833fce8..bfb45fb 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,13 @@ -# Courier PHP API library +# Courier PHP SDK -The Courier PHP library provides convenient access to the Courier REST API from any PHP 8.1.0+ application. +> **Beta**: The PHP SDK is in beta. APIs may change between releases. [Share feedback or report issues on GitHub.](https://github.com/trycourier/courier-php/issues/new) -It is generated with [Stainless](https://www.stainless.com/). - -## Documentation - -The REST API documentation can be found on [www.courier.com](https://www.courier.com/docs). +The Courier PHP SDK provides typed access to the Courier REST API from any PHP 8.1+ application. It uses named parameters for optional arguments and returns strongly typed response objects. ## Installation -To use this package, install via Composer by adding the following to your application's `composer.json`: - - +Add to your `composer.json`: ```json { @@ -29,169 +23,37 @@ To use this package, install via Composer by adding the following to your applic } ``` - +Then run `composer install`. -## Usage - -This library uses named parameters to specify optional arguments. -Parameters with a default value must be set by name. +## Quick Start ```php send->message( message: [ - 'to' => ['userID' => 'your_user_id'], - 'template' => 'your_template_id', - 'data' => ['foo' => 'bar'], - ], -); - -var_dump($response->requestId); -``` - -### Value Objects - -It is recommended to use the static `with` constructor `AudienceFilter::with(operator: 'MEMBER_OF', ...)` -and named parameters to initialize value objects. - -However, builders are also provided `(new AudienceFilter)->withOperator('MEMBER_OF')`. - -### Handling errors - -When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Courier\Core\Exceptions\APIException` will be thrown: - -```php -send->message( - message: [ - 'to' => ['userID' => 'your_user_id'], - 'template' => 'your_template_id', - 'data' => ['foo' => 'bar'], + 'to' => ['email' => 'you@example.com'], + 'content' => [ + 'title' => 'Hello from Courier!', + 'body' => 'Your first notification, sent with the PHP SDK.', ], - ); -} catch (APIConnectionException $e) { - echo "The server could not be reached", PHP_EOL; - var_dump($e->getPrevious()); -} catch (RateLimitException $e) { - echo "A 429 status code was received; we should back off a bit.", PHP_EOL; -} catch (APIStatusException $e) { - echo "Another non-200-range status code was received", PHP_EOL; - echo $e->getMessage(); -} -``` - -Error codes are as follows: - -| Cause | Error Type | -| ---------------- | ------------------------------ | -| HTTP 400 | `BadRequestException` | -| HTTP 401 | `AuthenticationException` | -| HTTP 403 | `PermissionDeniedException` | -| HTTP 404 | `NotFoundException` | -| HTTP 409 | `ConflictException` | -| HTTP 422 | `UnprocessableEntityException` | -| HTTP 429 | `RateLimitException` | -| HTTP >= 500 | `InternalServerException` | -| Other HTTP error | `APIStatusException` | -| Timeout | `APITimeoutException` | -| Network error | `APIConnectionException` | - -### Retries - -Certain errors will be automatically retried 2 times by default, with a short exponential backoff. - -Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default. - -You can use the `maxRetries` option to configure or disable this: - -```php - 0]); - -// Or, configure per-request: -$result = $client->send->message( - message: [ - 'to' => ['userID' => 'your_user_id'], - 'template' => 'your_template_id', - 'data' => ['foo' => 'bar'], - ], - requestOptions: ['maxRetries' => 5], -); -``` - -## Advanced concepts - -### Making custom or undocumented requests - -#### Undocumented properties - -You can send undocumented parameters to any endpoint, and read undocumented response properties, like so: - -Note: the `extra*` parameters of the same name overrides the documented parameters. - -```php -send->message( - message: [ - 'to' => ['userID' => 'your_user_id'], - 'template' => 'your_template_id', - 'data' => ['foo' => 'bar'], - ], - requestOptions: [ - 'extraQueryParams' => ['my_query_parameter' => 'value'], - 'extraBodyParams' => ['my_body_parameter' => 'value'], - 'extraHeaders' => ['my-header' => 'value'], ], ); -``` - -#### Undocumented request params - -If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above. - -#### Undocumented endpoints - -To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so: - -```php -request( - method: "post", - path: '/undocumented/endpoint', - query: ['dog' => 'woof'], - headers: ['useful-header' => 'interesting-value'], - body: ['hello' => 'world'] -); +var_dump($response->requestId); ``` -## Versioning +The client reads your API key from the constructor argument. Set `COURIER_API_KEY` in your environment and pass it with `getenv('COURIER_API_KEY')`. -This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time. - -This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes. - -## Requirements - -PHP 8.1.0 or higher. +## Documentation -## Contributing +Full documentation: **[courier.com/docs/sdk-libraries/php](https://www.courier.com/docs/sdk-libraries/php/)** -See [the contributing documentation](https://github.com/trycourier/courier-php/tree/main/CONTRIBUTING.md). +- [Quickstart](https://www.courier.com/docs/getting-started/quickstart/) +- [Send API](https://www.courier.com/docs/platform/sending/send-message/) +- [API Reference](https://www.courier.com/docs/reference/get-started/)