Skip to content

Architecture and Packages

The Composer and npm packages that make up Shopper 3, how they depend on each other, and the two ways a storefront reads store data.

Shopper 3 is split into 13 Composer packages and 2 npm packages. They are developed together in the shopperlabs/shopper repository, as the Contributing page explains. Each release tags the Composer packages and @shopperlabs/shopper-types at the same version; @shopperlabs/shopper-sdk is published with a version number of its own. Your application requires shopper/framework, then adds the Store API, a payment driver or a carrier driver when the store needs one.

Packages

Each package has one job. The last column tells whether Composer installs the package as a dependency of another one, or whether you require it yourself.

PackageRoleInstalled by
shopper/frameworkThe admin panel: Livewire pages and components, roles and permissions, media on the catalog models, the shopper:install and shopper:user commandsYou
shopper/coreThe e-commerce engine: models and their contracts, migrations, enums, observers, stock, prices, channels, search, outgoing webhooksshopper/framework
shopper/cartCarts and their totals pipeline (lines, automatic promotions, discount codes, taxes), and the creation of an order from a cartshopper/framework
shopper/paymentThe payment manager and its manual driver, payment transactions, payment provider events, reconciliation of pending paymentsshopper/framework
shopper/shippingThe shipping manager and its manual driver, carrier rates, shipment tracking syncshopper/framework
shopper/sidebarThe navigation builder behind the admin panel sidebarshopper/framework
shopper/apiThe Store API: catalog, cart, checkout, customer and order endpoints as JSON:API under /store, and the shopper:api:install commandYou
shopper/httpThe HTTP layer of the Store API: route groups, rate limiters, CORS, and the middleware that resolves the channel, zone, locale and customer of a requestshopper/api
shopper/stripeThe stripe payment driverYou
shopper/fedexThe fedex carrier driver: live rates and trackingYou
shopper/upsThe ups carrier driver: live rates and trackingYou
shopper/uspsThe usps carrier driver: live ratesYou
shopper/upgradeThe shopper:upgrade command that moves a 2.x store to 3.x, required as a dev dependency and removed after the upgradeYou
@shopperlabs/shopper-sdkThe JavaScript client of the Store APIYou (npm)
@shopperlabs/shopper-typesThe TypeScript types of the Store API resources@shopperlabs/shopper-sdk

shopper/core, shopper/cart, shopper/payment, shopper/shipping and shopper/http are not meant to be required on their own. Core binds its model contracts to the classes listed in config/shopper/models.php, a file that shopper/framework ships, so an application always starts from shopper/framework.

shopper/sidebar is the exception: it does not depend on any other Shopper package and works in any Laravel application that runs Livewire 4.

Dependencies

Every Shopper Composer package requires its Shopper dependencies at self.version, so Composer keeps all the Shopper packages of an application on the same version.

PackageShopper packages it requiresMain third-party packages
shopper/frameworkcore, cart, payment, shipping, sidebarfilament/filament, spatie/laravel-medialibrary, spatie/laravel-permission, laravel/passkeys
shopper/coreNonelaravel/scout, league/csv, staudenmeir/laravel-adjacency-list, giggsey/libphonenumber-for-php
shopper/cartcoreNone
shopper/paymentcoreNone
shopper/shippingcoreNone
shopper/sidebarNonelivewire/livewire
shopper/apicore, cart, payment, shipping, httpspatie/laravel-query-builder, spatie/laravel-medialibrary
shopper/httpcorelaravel/sanctum
shopper/stripepaymentstripe/stripe-php
shopper/fedexcore, shippingNone
shopper/upscore, shippingNone
shopper/uspsshippingNone
shopper/upgradeNonerector/rector

shopper/api does not list shopper/framework in its composer.json, but it runs next to it: the customer endpoints need the Shopper\Traits\InteractsWithShopper trait on your User model, which shopper/framework provides. Install the Store API in an application where shopper/framework is already installed and migrated.

On the npm side, @shopperlabs/shopper-sdk depends on @shopperlabs/shopper-types and re-exports its types, so a storefront installs the SDK only. @shopperlabs/shopper-types has no dependency and can be installed alone in a project that calls the Store API with its own HTTP client.

What shopper/framework Installs

composer require shopper/framework installs the admin panel and five Shopper packages: core, cart, payment, shipping and sidebar. It also brings Filament 5, Livewire 4, Spatie Media Library and Spatie Laravel Permission, along with smaller packages for two-factor authentication, passkeys, charts and barcodes.

With this single package, a store has its admin panel, its catalog, carts and orders, the manual payment driver and the manual shipping driver. These packages are not installed until you require them:

  • shopper/api and shopper/http, for a storefront that runs outside your Laravel application;
  • shopper/stripe, to take card payments with Stripe;
  • shopper/fedex, shopper/ups and shopper/usps, for live carrier rates;
  • shopper/upgrade, to move a 2.x store to 3.x.

The Installation page installs shopper/framework and the Store API, and the Payments and Carriers pages cover the drivers.

Service Providers

Every Composer package registers one service provider through Laravel package discovery, declared under extra.laravel.providers in its composer.json. You have nothing to add to bootstrap/providers.php.

Service providerPackageWhat it registers
Shopper\ShopperServiceProvidershopper/frameworkThe admin routes, the Livewire pages and components, the sidebar, the settings and themes, the admin commands
Shopper\Core\CoreServiceProvidershopper/coreThe model contract bindings, the morph map, the observers, the price, stock and channel services, the order reclaim and webhook redispatch tasks
Shopper\Cart\CartServiceProvidershopper/cartThe Cart and CartLine bindings, the cart pipeline, the promotion and discount services, the shopper:prune-carts task
Shopper\Payment\PaymentServiceProvidershopper/paymentThe Payment manager, the payment session gateway, the shopper:payments:reconcile task
Shopper\Shipping\ShippingServiceProvidershopper/shippingThe Shipping manager, the carrier rate service, the shopper:shipments:sync-tracking task
Shopper\Sidebar\SidebarServiceProvidershopper/sidebarThe sidebar Livewire component and its assets
Shopper\Api\ApiServiceProvidershopper/apiThe /store routes, the shopper:api:install command, the daily sanctum:prune-expired task
Shopper\Http\HttpServiceProvidershopper/httpThe shopper:store, shopper:store-auth and shopper:store-webhook middleware groups, the rate limiters, the zone and channel resolvers, the CORS paths, the JSON:API error renderer
Shopper\Stripe\StripeServiceProvidershopper/stripeThe stripe payment driver
Shopper\FedEx\FedExServiceProvidershopper/fedexThe fedex shipping driver
Shopper\Ups\UpsServiceProvidershopper/upsThe ups shipping driver
Shopper\Usps\UspsServiceProvidershopper/uspsThe usps shipping driver
Shopper\Upgrade\UpgradeServiceProvidershopper/upgradeThe shopper:upgrade command and its steps

The providers of framework, core, cart and payment load their migrations from the package: php artisan migrate runs them from vendor/, and they are never published. The installers publish only the migrations of third-party packages: shopper:install the Spatie Media Library one, shopper:api:install the Laravel Sanctum one.

Payment and carrier drivers plug into two Laravel managers. Shopper\Payment\PaymentManager and Shopper\Shipping\ShippingManager each provide a manual driver. shopper/stripe adds the stripe driver with Payment::extend(), and the carrier packages add fedex, ups and usps with Shipping::extend(). A driver of your own registers the same way, as Custom Drivers and Custom Shipping Drivers show.

Configuration Files

Each package merges its configuration under the shopper key, one file per key: config/shopper/cart.php is read with config('shopper.cart'). The shopper-config publish tag groups the files of every installed Shopper package, which is why php artisan shopper:install also publishes api.php and http.php once shopper/api is installed. Drivers use a tag of their own, so their file is published only when you ask for it.

PackageFiles in config/shopper/Publish tag
shopper/frameworkaddons.php, admin.php, auth.php, features.php, media.php, models.php, routes.php, settings.php, themes.phpshopper-config
shopper/corecore.php, orders.php, search.php, webhooks.phpshopper-config
shopper/cartcart.phpshopper-config
shopper/paymentpayment.phpshopper-config
shopper/shippingshipping.phpshopper-config
shopper/apiapi.phpshopper-config
shopper/httphttp.phpshopper-config
shopper/stripestripe.phpshopper-stripe-config
shopper/fedexfedex.phpshopper-fedex-config
shopper/upsups.phpshopper-ups-config
shopper/uspsusps.phpshopper-usps-config

shopper/sidebar keeps its file outside this folder: config/sidebar.php, read with config('sidebar') and published with the sidebar-config tag. shopper:install does not publish it. shopper/upgrade has no configuration file.

shopper/framework also writes the component files of the admin panel to config/shopper/components/ when you run php artisan shopper:component:publish, as described in Components. The Configuration page describes what each file holds.

Reading Store Data

A storefront reaches the store data in one of two ways, depending on where it runs: inside your Laravel application, or as a separate application that calls the Store API.

From Your Laravel Application

A storefront rendered by the same Laravel application, with Blade, Livewire or Inertia, queries the Shopper models with Eloquent and needs no extra package. Resolve a model through its contract, so the class you set in config/shopper/models.php is the one queried:

app/Http/Controllers/ShopController.php
namespace App\Http\Controllers;

use Illuminate\Contracts\View\View;
use Shopper\Core\Models\Contracts\Product;

final class ShopController extends Controller
{
    public function index(): View
    {
        $products = resolve(Product::class)::query()
            ->publish()
            ->with('brand')
            ->latest('published_at')
            ->paginate(24);

        return view('shop.index', ['products' => $products]);
    }
}

The publish scope keeps the products that are visible and whose publication date has passed. The Models page lists every model with its contract.

The visitor's cart lives in the session: the Shopper\Cart\Facades\Cart facade returns it with Cart::current(), or null while the visitor has no cart and shopper.cart.session.auto_create is off, its default. The Cart page covers the cart in detail.

The routes that receive payment and carrier webhooks, POST /store/webhooks/{driver} and POST /store/webhooks/shipping/{driver}, are registered by shopper/api. Without that package, a payment provider such as Stripe has no route to notify your store.

Through the Store API

A storefront that runs elsewhere, such as a Next.js or Nuxt site or a mobile app, calls the Store API. shopper/api serves the catalog, carts, checkout, customer accounts and orders as JSON:API documents under /store. shopper/http holds the layer around these endpoints: the route groups, the rate limiters, CORS on the store routes, and the middleware that resolves the channel from the X-Shopper-Channel header, the zone from X-Shopper-Zone, the locale from Accept-Language and the customer from a Laravel Sanctum token.

The prefix comes from config('shopper.http.prefix'), which reads the SHOPPER_API_PREFIX environment variable. The Installation page installs the Store API.

The JavaScript SDK wraps these endpoints and returns the nested objects described by @shopperlabs/shopper-types. It runs wherever fetch exists: browsers, Node.js 18+, React Native and edge runtimes.

npm install @shopperlabs/shopper-sdk

This script creates a client for the store and lists the 12 newest products whose name contains "t-shirt":

import Shopper from '@shopperlabs/shopper-sdk'

const sdk = new Shopper({ baseUrl: 'https://shop.example.com' })

const { data: products } = await sdk.store.product.list({
  filter: { name: 't-shirt' },
  sort: ['-published_at'],
  page: { size: 12 },
})

The SDK calls /store by default; set its storePrefix option when you change the API prefix. The Storefront section covers the endpoints, and the JavaScript SDK pages the client in detail.

Last updated on

Edit on GitHub