Laravel Starter Kit Laravel Package

Getting Started

Still a template repo, not a package — you don't composer require it into an existing app. Start from 3.0.0:

composer create-project salla/laravel-starter-kit my-salla-app
cd my-salla-app && cp .env.example .env && php artisan key:generate

3.0.0 is mostly a big dependency consolidation (dozens of Dependabot bumps merged in one go) plus a reorganized webhooks section in the README. That README pass is the first thing to read — it's the only place the event list and payload shapes are documented in-tree.

First places to look, in order:

1. routes/ — install flow, OAuth callback, and webhook endpoints.
2. .env.example / config/salla.php — SALLA_CLIENT_ID, SALLA_CLIENT_SECRET, SALLA_REDIRECT_URI, SALLA_WEBHOOK_SECRET.
3. composer.json — confirm what you actually got. This release lands on laravel/framework 8.83.x and salla/ouath2-merchant 1.4.0 (note the typo in the package name — it's upstream, not you).
4. The OAuth callback controller — where tokens land.
5. app/Actions/ — the starter now pulls lorisleiva/laravel-actions 2.4.x; business logic is expected to live in action classes, not controllers or raw jobs.
6. Middleware — "current store" resolution from the incoming request.

First use case: install the app on a dev store.

• Create an app in the Salla Partners dashboard.
• Redirect/callback → tunnel, e.g. https://<ngrok-id>.ngrok.io/salla/callback.
• Subscribe to app.store.authorize and order.created.
• php artisan serve behind the tunnel, install on a test store, verify: token row written, callback 200, webhook payload in storage/logs/laravel.log.

Implementation Patterns

OAuth / Easy Mode flow. The starter handles the auth-code exchange via salla/ouath2-merchant. 3.0.0 bumps it 1.0.0 → 1.4.0, so treat the package as the source of truth for the exchange and token shape — don't hand-roll HTTP calls against the token endpoint, and re-read that package's changelog if you're upgrading an existing install. Add onboarding after the token save, never inside the callback controller; that controller must stay fast and idempotent.

Actions as the unit of work. With laravel-actions in the stack, the natural shape is:

verify signature → resolve store → MyEventAction::dispatch($storeId, $payloadId) → return 200

The same action class is callable three ways — from the webhook controller, from the queue, from php artisan — which kills the "test it by reinstalling" loop. Keep one action per event and an event→action map in config so adding a webhook is a one-line change and reviewers can see coverage in a single file.

Token-per-store model. Every Salla API call is scoped to a store, not a user. Pass the store_id explicitly into actions and requests. Salla apps are largely server-to-server; don't build features that assume a Laravel session.

Wrap the API client. Nothing outside the client touches raw tokens. Centralize SallaClient::for($store) — token lookup, proactive refresh, retry/backoff, error normalization. Everything else asks for a store-scoped client.

Agency / multi-app extension. Running several Salla apps off one codebase? Add an apps table and key tokens by (app_id, store_id). Branch config before requests reach controllers.

Local dev loop as a standing pattern. Tunnel + Partners dashboard + webhook replay is your inner loop. Keep a php artisan salla:replay <event> command that constructs the payload and calls the action directly — a few lines now that actions are first-class.

Gotchas and Tips

• You are on Laravel 8, and it's EOL. 3.0.0 finished on laravel/framework 8.83.x, not 9/10/11. If your org requires a supported major, budget a service-provider + Breeze + Inertia upgrade pass before you commit to the starter — $bindings/$singletons closure style and the Breeze scaffolding are the usual friction.
• The frontend dep sweep is the sneaky breaking change. daisyui 1.x → 3.x across this release range changes component class names and Tailwind config shape. If you kept the stock Breeze/Inertia UI, your screens will look wrong until you re-check the Tailwind + daisyUI config. axios, postcss, qs, json5, decode-uri-component bumps are security fixes — run npm install clean rather than restoring an old lockfile.
• The release notes are truncated (larave… mid-list). Don't infer the full diff from them — run composer outdated / read composer.lock after install.
• HTTPS-only callbacks. Salla rejects http://localhost. Always tunnel.
• Signature verification on the raw body. HMAC $request->getContent() bytes, not the parsed array. Re-encoding JSON breaks signatures — this is the #1 "webhook always fails" cause.
• Config cache bites on secret rotation. After changing SALLA_*, run php artisan config:clear, and clear config:cache on your queue workers too.
• Token refresh: refresh early, lock it. Refresh before expiry and wrap it in Cache::lock("salla:refresh:$storeId"). Refresh-on-401 gives spiky latency and thundering-herd refreshes from parallel jobs.
• Webhooks are at-least-once. Persist a processed-event ID, or use ShouldBeUnique — with laravel-actions the uniqueness middleware goes on the action/job, not the controller. Duplicate order.created double-charging customers is a real, common failure.
• Don't pass fat payloads into actions. Queued actions serialize constructor args; Eloquent models use SerializesModels but raw arrays don't compress. Pass the store id + the webhook event row id, and re-fetch inside handle() — otherwise large order payloads bloat the queue table.
• Store resolution middleware. Custom-mode requests carry the store identifier in headers. If your middleware throws on unknown stores instead of returning 401/403, callbacks become opaque. Log header + store id at debug on failure.
• Rate limits are per app/store. Route outbound calls through a queue with RateLimiter::for('salla', ...). Failed-webhook retries stack up and burn quota fast.
• Locale & RTL are day-one. Salla's audience is Arabic-first. Add dir="rtl" and lang/ar scaffolding before building screens you'd retrofit.
• Log the raw webhook body + headers before verification. Once a signature check fails and the payload is swallowed, you can't debug it.
• Treat it as your code, not a dependency. Watch upstream for auth/webhook fixes (the 3.0.0 README webhook reorganization is worth re-reading), but cherry-pick rather than composer update — you own the integration surface.