Download the PHP package antoniadisio/creem-php without Composer

Creem PHP SDK

Unofficial but passionate PHP SDK for Creem, with a typed client facade, resource DTOs, credential profiles, and webhook verification helpers.

This is an independently maintained personal package published under the antoniadisio namespace. It is not an official Creem package and is not distributed by Creem.

The public contract centers on a typed Antoniadisio\Creem\Client facade for outbound API access, named credential profile helpers for multi-account integrations, and a stateless Antoniadisio\Creem\Webhook helper for inbound webhook verification and parsing. saloonphp/saloon is used internally for transport only and is not part of the supported consumer-facing API.

Installation

Requires PHP 8.4 or newer. The runtime namespace is Antoniadisio\Creem\.

Release history and migration notes live in the GitHub changelog.

Audience

• Integrators: use this README and the supported public API in Antoniadisio\Creem\Client, Config, Webhook, Resource\*, Dto\*, Enum\*, and Exception\*.
• Contributors: use the GitHub contributor guide.
• Repository workflow and releases: use the GitHub contributor guide, the release guide, and the live playground runbook.

This README stays consumer-focused. Repository workflow, releases, and live verification procedures live in the linked repo docs.

Everything under Antoniadisio\Creem\Internal\* is shipped for runtime support only and is not part of the supported consumer-facing API.

Quick Start

Product responses expose custom_fields as typed Antoniadisio\Creem\Dto\Common\CustomField objects via $product->customFields.

Antoniadisio\Creem\Config defaults to Environment::Production. If you are using test API keys or test resource IDs, set Environment::Test explicitly. Creem's marketing/docs may also call the test environment "sandbox", but the SDK does not expose a separate sandbox environment.

Configuration

Antoniadisio\Creem\Config is immutable and accepts:

• apiKey (required; current Creem keys use creem_test_... for Environment::Test and creem_... for Environment::Production)
• environment (Antoniadisio\Creem\Enum\Environment::Production by default)
• baseUrl (optional override, must be a valid https:// URL)
• timeout (optional request timeout in seconds, defaults to 30)
• userAgentSuffix (optional suffix appended to the SDK user agent)
• allowUnsafeBaseUrlOverride (optional, defaults to false; required only when baseUrl uses a non-Creem host)

Environments resolve to:

• Environment::Production -> https://api.creem.io
• Environment::Test -> https://test-api.creem.io

The SDK validates Creem-prefixed keys against the configured environment. creem_test_... keys are only accepted with Environment::Test, and creem_... production keys are only accepted with Environment::Production.

When baseUrl is provided, Config now enforces trusted-host mode by default and only allows official Creem hosts (api.creem.io, test-api.creem.io). To target a non-official host (for example a local proxy), you must opt in explicitly with allowUnsafeBaseUrlOverride: true.

Config also redacts the API key in debug output, string casts, and serialization.

Transport defaults are hardened: redirects are disabled, TLS certificate verification is always enabled, TLS 1.2 is enforced as the minimum protocol, and request/connect/read timeouts all use the configured SDK timeout (or the 30-second default).

Credential Profiles

For first-class multi-account integrations, use named credential profiles instead of trying to overload one Config with multiple API keys or webhook secrets.

Antoniadisio\Creem\CredentialProfile mirrors the Config inputs for one concrete credential set and adds an optional webhookSecret. Antoniadisio\Creem\CredentialProfiles stores named profiles, and Antoniadisio\Creem\ClientFactory lazily builds one Client per profile.

The low-level single-key API remains available when you only need one credential set. The multi-profile layer is the recommended SDK path when you need to route requests or webhooks across multiple Creem accounts or app surfaces.

Error Handling

All SDK exceptions extend Antoniadisio\Creem\Exception\CreemException.

• AuthenticationException for 401
• ForbiddenException for 403
• ConflictException for 409
• GoneException for 410
• ValidationException for 422 and validation-style client payloads
• NotFoundException for 404
• RateLimitException for 429 (retryAfterSeconds() exposes the parsed Retry-After delay when the API sends one)
• ServerException for 5xx
• TransportException for transport, timeout, and decode failures
• WebhookException for inbound webhook verification and parsing failures
• InvalidWebhookSignatureException for invalid or blank creem-signature headers
• InvalidWebhookPayloadException for malformed webhook payloads

Webhooks

Antoniadisio\Creem\Webhook verifies the incoming creem-signature header against the raw request body and parses the JSON payload without requiring a Client instance. Creem currently sends creem-signature as the raw HMAC digest of the payload, for example 63dcbb00f44e82ac158edfb75fd745286f99e9bcebed04dbc0133bb20d15d09c.

You can also pass an optional replay callback to Webhook::constructEvent(...). The callback receives the parsed WebhookEvent; return true to reject already-seen events:

Always verify the exact raw request body. Do not json_decode(), re-encode, trim, or otherwise mutate the payload before calling Webhook::verifySignature() or Webhook::constructEvent(), or the HMAC check will fail. The SDK also rejects webhook payloads larger than 1 MiB before decoding.

When multiple webhook secrets exist, resolve the intended named profile first and use the profile-aware helpers instead of trying every secret blindly:

Webhook::verifySignatureForProfile(...) and Webhook::constructEventForProfile(...) resolve exactly one secret from the named profile. The SDK does not iterate across every configured secret for you.

For local webhook development and manual dashboard test sends, the maintainer runbook in the GitHub playground guide documents the php -S plus ngrok flow and the per-route/profile verification checklist.

For Laravel-style controllers, use the raw request content instead of decoded request input:

The returned WebhookEvent exposes id(), eventType(), eventTypeEnum(), createdAt(), object(), payload(), and toArray(). eventType() remains the raw string from Creem for forward compatibility, while eventTypeEnum() returns a WebhookEventType for currently documented events or null for unknown future values. object() returns a StructuredObject, so consumers can read nested webhook data without decoding JSON again. Live Creem deliveries currently send created_at as a Unix epoch timestamp; the SDK normalizes that to DateTimeImmutable for you.

Resources

Antoniadisio\Creem\Client exposes these resource accessors:

• products()
• customers()
• subscriptions()
• checkouts()
• licenses()
• discounts()
• transactions()
• stats()

All mutating resource methods accept an optional final ?string $idempotencyKey = null argument. Pass a stable key on retries to prevent duplicate checkout, subscription, discount, or license side effects.

Mutation request DTOs now fail fast with InvalidArgumentException when required identifiers are blank after trimming, numeric bounds are invalid (for example price <= 0 or units <= 0), discount payload fields are incoherent (fixed vs percentage), or list elements are malformed at runtime. Existing integrations that relied on sending empty/invalid payload values should update those call sites before upgrading.

Mutating resource methods that interpolate IDs into path segments (subscriptions()->cancel/update/upgrade/pause/resume and discounts()->delete) now normalize IDs and reject unsafe input. IDs are trimmed, must be non-blank, may not be dot segments (. or ..), and may only contain [A-Za-z0-9._-]; reserved URI/control characters (/, \\, ?, #, %, ASCII controls) are rejected to prevent route manipulation.

Products

Supported methods:

• get(string $id)
• create(CreateProductRequest $request)
• search(?SearchProductsRequest $request = null)

Customers

Supported methods:

• list(?ListCustomersRequest $request = null)
• get(string $id)
• findByEmail(string $email)
• createBillingPortalLink(CreateCustomerBillingPortalLinkRequest $request)

Subscriptions

Supported methods:

• get(string $id)
• cancel(string $id, ?CancelSubscriptionRequest $request = null)
• update(string $id, UpdateSubscriptionRequest $request)
• upgrade(string $id, UpgradeSubscriptionRequest $request)
• pause(string $id)
• resume(string $id)

For live seat updates, prefer priceId on UpsertSubscriptionItem and pass the current subscription item id when adjusting an existing line item. Creem's API troubleshooting guidance recommends price_id as the most specific reference for validation. When setting updateBehavior on subscriptions()->update(...), SubscriptionUpdateBehavior::ProrationChargeImmediately applies the unit change immediately and may generate a proration charge right away. In live testing, SubscriptionUpdateBehavior::ProrationCharge and SubscriptionUpdateBehavior::ProrationNone left the current item units unchanged until the next billing boundary.

Checkouts

Supported methods:

• get(string $id)
• create(CreateCheckoutRequest $request)

Licenses

Supported methods:

• activate(ActivateLicenseRequest $request)
• deactivate(DeactivateLicenseRequest $request)
• validate(ValidateLicenseRequest $request)

Discounts

Supported methods:

• get(string $id)
• getByCode(string $code)
• create(CreateDiscountRequest $request)
• delete(string $id)

Transactions

Supported methods:

• get(string $id)
• search(?SearchTransactionsRequest $request = null)

Stats

Supported methods:

• summary(GetStatsSummaryRequest $request)

Response Shapes

Collection-style endpoints return Antoniadisio\Creem\Dto\Common\Page, with pagination metadata in Antoniadisio\Creem\Dto\Common\Pagination. Resource items are exposed through typed DTO payloads instead of raw decoded arrays.

Closed-set response fields are hydrated to Antoniadisio\Creem\Enum\* cases, spec-defined date-time fields are hydrated to DateTimeImmutable, and malformed required payloads now raise Antoniadisio\Creem\Exception\HydrationException instead of being silently coerced.