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.0+
• PSR-18 HTTP client (Guzzle 7 by default; any compliant client via constructor injection)
• 74 typed sub-clients covering the full REST surface

Install

From Packagist (recommended)

composer require shoper/sdk

From a local path (SDK developer or pre-release testing)

In your app's composer.json:

{
    "repositories": [
        { "type": "path", "url": "/absolute/path/to/shoper-openapi/sdk/php/bootstrap" }
    ],
    "require": { "shoper/sdk": "@dev" },
    "minimum-stability": "dev",
    "prefer-stable": true
}

Then composer require shoper/sdk resolves to the path repo.

From VCS (fork or branch you haven't published yet)

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/dreamcommerce/shoper-php-sdk" }
    ],
    "require": { "shoper/sdk": "dev-faza-3-php-sdk" }
}

Quick start

Authenticate (admin Basic Auth → token)

use Shoper\Sdk\ShoperClient;

$client = new ShoperClient('https://yourshop.shoparena.pl');
$auth = $client->authenticate('admin-user', 'admin-pass');
$client->setToken($auth['access_token']);

Authenticate (OAuth authorization-code, AppStore apps)

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

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;

foreach (new Paginator($client->products(), 'listProducts') as $product) {
    // streams across all pages, transparent
}

Verify a webhook

use Shoper\Sdk\WebhookVerifier;

$verifier = new WebhookVerifier($appstoreSecret);
if (!$verifier->verify($_SERVER['HTTP_X_SHOPER_HMAC_SHA256'] ?? '', file_get_contents('php://input'))) {
    http_response_code(401);
    exit;
}

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://docs.shoper.pl
• Issue tracker / source: https://github.com/dreamcommerce/shoper-php-sdk
• Local-test harness (path-repo example): sdk/php/local-test/ in the source repo

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.