README

Official PHP SDK for the Shoper REST API. Generated from OpenAPI 3.1 (Fern), with hand-written ergonomic helpers (ShoperClient, OAuthManager, WebhookVerifier, Paginator, BulkRequestBuilder, RateLimitHandler).

PHP 8.1+
PSR-18 HTTP client (any compliant implementation, e.g. Guzzle 7 — auto-discovered via php-http/discovery or injected via constructor)
74 typed sub-clients covering the full REST surface

Install

composer require shoper/sdk

Quick start

Authenticate (admin Basic Auth → token)

use Shoper\Sdk\ShoperClient;

$client = new ShoperClient('https://yourshop.shoparena.pl');
$client->authenticate('admin-user', 'admin-pass');   // fetches and stores the token

Authenticate (OAuth authorization-code, AppStore apps)

$auth = $client->authenticateOAuth($clientId, $clientSecret, $authorizationCode);
// later, when access_token expires:
$auth = $client->refreshToken($clientId, $clientSecret, $auth['refresh_token']);

Both calls store the new access token on the client automatically. An existing token can also be injected directly: new ShoperClient($url, $accessToken) or $client->setToken($accessToken).

List products

$page = $client->products()->listProducts();   // typed ListProductsResponse, default page
foreach ($page->list as $p) {
    echo $p->productId . ' ' . $p->translations['pl_PL']->name . "\n";
}

Iterate every page

use Shoper\Sdk\Paginator;
use Shoper\Sdk\Rest\Products\Requests\ListProductsRequest;

$fetch = fn (array $params) => (array) $client->products()->listProducts(new ListProductsRequest($params));

foreach (new Paginator($fetch, limit: 50) as $product) {
    // streams across all pages, transparent
}

Verify a webhook

use Shoper\Sdk\WebhookVerifier;

$verifier = new WebhookVerifier($appstoreSecret, $webhookSecret);
if (!$verifier->verifyFromGlobals(file_get_contents('php://input'))) {
    http_response_code(401);
    exit;
}

verifyFromGlobals() reads the X-Webhook-Id, X-Shop-License and X-Webhook-SHA1 headers; verifyFromPsr7($request) does the same for a PSR-7 request. See examples/03-webhook-verification.php.

All 74 sub-clients

Every public REST resource is a typed getter on ShoperClient:

$client->products();           // \Shoper\Sdk\Rest\Products\ProductsClient
$client->orders();             // \Shoper\Sdk\Rest\Orders\OrdersClient
$client->categories();
// ... 71 more — see scripts/sub-clients.expected.php for the canonical list

For brand-new resources Fern adds before this README is regenerated, the magic __call fallback still works.

Features

OAuth 2.0 authorization_code + refresh_token flows
Admin Basic authentication
Type-safe response DTOs (generated from OpenAPI spec)
Paginator — iterate through all pages
BulkRequestBuilder — batch up to 25 operations in one call
RateLimitHandler — automatic retry on 429 with Retry-After honor
WebhookVerifier — HMAC signature verification

Examples

See examples/ directory for end-to-end scenarios:

01-oauth-flow.php — full AppStore OAuth flow
02-basic-crud.php — list / create / update / delete
03-webhook-verification.php — receive and verify webhooks
04-pagination.php — iterate all pages
05-bulk-requests.php — batch updates
06-rate-limit.php — retry with backoff
07-error-handling.php — typed exceptions

Reference

API docs: https://developers.shoper.pl
Issue tracker / source: https://github.com/dreamcommerce/shoper-sdk-php
Packagist: https://packagist.org/packages/shoper/sdk

Support

Bug reports and feature requests: contact Shoper support. This repository does not accept public issues or direct PRs to auto-generated code.

Community PRs are welcome to:

src/ShoperClient.php and other root helpers (src/*.php)
README.md, examples/, tests/Helpers/
CHANGELOG.md, .github/

Paths src/Rest/** are auto-generated from the OpenAPI spec and cannot be modified directly — PRs touching them will be auto-closed.

License

MIT — see LICENSE.

shoper / sdk

Maintainers

Package info

Statistics

Security