pankrok / shoper-appstore-bundle

2.2.0 2026-09-17 05:12 UTC

Requires

• php: >=8.2
• doctrine/dbal: ^3.8|^4
• doctrine/doctrine-bundle: ^2.13
• doctrine/doctrine-migrations-bundle: ^3.3
• doctrine/orm: ^3.2
• symfony/console: 7.4.*
• symfony/framework-bundle: 7.4.*
• symfony/http-client: 7.4.*
• symfony/monolog-bundle: ^3.7|^4.0
• symfony/twig-bundle: 7.4.*
• symfony/yaml: 7.4.*
• twig/extra-bundle: ^3.12
• twig/twig: ^3.12

Requires (Dev)

• phpunit/phpunit: ^11.5
• symfony/debug-bundle: 7.4.*
• symfony/dotenv: 7.4.*
• symfony/maker-bundle: ^1.60
• symfony/phpunit-bridge: ^7.4|^8.0
• symfony/stopwatch: 7.4.*
• symfony/web-profiler-bundle: 7.4.*

MIT

• Jerzy Róg

• api
• appstore
• shoper

Published on Packagist.org on 2026-09-17 05:13 UTC

README

Unofficial Symfony 7.4 bundle for building applications on the Shoper Appstore. Provides OAuth integration, REST API client, billing and webhook handling, Twig helpers, and Maker commands for scaffolding controllers. Not official Shoper software.

Current version: 2.2.0

Table of contents

• Technologies
• Setup
• Configuration
• Token refresh CRON
• Error handling
• Documentation

Technologies

• PHP 8.2
• Symfony 7.4 LTS
• Doctrine ORM
• Twig
• Symfony HttpClient
• Symfony MakerBundle

Setup

Install via Composer:

composer require pankrok/shoper-appstore-bundle "^2.0.0"

Create the database tables:

php bin/console make:migration
php bin/console doctrine:migrations:migrate

Configuration

OAuth mode (Appstore)

Create config/packages/appstore.yaml:

shoper_appstore:
    appId: your_app_id
    appSecret: your_app_secret
    appstoreSecret: your_appstore_secret
    jssdk: https://dcsaascdn.net/js/dc-sdk-1.0.5.min.js

Basic Auth mode (admin username/password)

shoper_appstore:
    username: admin_username
    password: admin_password
    shopurl: https://yourshop.com
    jssdk: https://dcsaascdn.net/js/dc-sdk-1.0.5.min.js

Rate limiting (optional)

shoper_appstore:
    # ...
    rateLimit:
        maxRetries: 3   # retries after HTTP 429, honouring Retry-After (0 disables)
        throttle: true  # wait when the shop reports a full X-SHOP-API-* bucket

Token refresh CRON

Run the token refresh command every 4 hours to keep OAuth tokens valid:

php bin/console shoper:token:refresh

Available options:

Option	Default	Description
--limit	200	Maximum number of tokens to refresh per run
--hours-ahead	23	Refresh tokens expiring within this many hours (max 23)

Example crontab entry (every 4 hours):

0 */4 * * * cd /var/www/html && php bin/console shoper:token:refresh --limit=200 --hours-ahead=23

Note: The old command name ShoperAppstoreBundle:TokenRefresh is kept as a BC alias.

Error handling

All Shoper API errors throw ShoperApiException, which extends Symfony's HttpException and carries the original error code and description from the API response.

The bundle ships an ExceptionSubscriber that automatically intercepts ShoperApiException and renders a clean Aurora-compatible error page instead of the Symfony debug page — no configuration needed.

To override the error template in your application, create:

templates/bundles/Appstore/error.html.twig

Catching the exception manually in a controller:

use PanKrok\ShoperAppstoreBundle\Exception\ShoperApiException;

try {
    $data = $api->product->get()->getBodyArray();
} catch (ShoperApiException $e) {
    // $e->getShoperError()            → 'invalid_token'
    // $e->getShoperErrorDescription() → 'Token has expired'
    // $e->getStatusCode()             → 401
    throw $e;
}

Tests

The suite is pure unit tests (no kernel, database or network — HTTP goes through MockHttpClient):

composer install
vendor/bin/phpunit

Documentation

Topic	File
ApiController reference	docs/APICONTROLLER.md
OAuth & Basic Auth	docs/AUTH.md
Aurora forms	docs/AURORAFORMS.md
Billing system	docs/BILLING.md
Events	docs/EVENTS.md
Iframe / JS SDK	docs/IFRAME.md
API Resources	docs/RESOURCES.md
Shoper Controller	docs/SHOPERCONTROLLER.md
Twig filters	docs/TWIGFILTERS.md
Webhooks	docs/WEBHOOK.md