Ecommerce Admin Livewire Laravel Package

Getting Started

This package is the Livewire admin UI for the ArtisanPack UI ecommerce engine — it does not ship its own commerce domain, it renders and operates the engine's orders, products, customers, promotions, shipping, tax, and reports. Treat it as the operator console you get for free once the engine is in place.

Requirements are tight and worth verifying before you start: engine 1.0, Laravel 12 or 13, Livewire 3.6+ or 4. Install the engine and run its migrations first, then:

composer require artisanpack-ui/ecommerce-admin
php artisan ecommerce-admin:install
php artisan ecommerce:sync-permissions

ecommerce-admin:install publishes the config, walks the front-end steps, runs an access check, and seeds notification templates. If the access check fails, it is almost always the middleware or missing permissions, not the install.

Where to look first:

1. The published config — routes/prefix, the admin middleware stack, real-time toggles, and the extension registration points live here.
2. The extension registries — navigation, dashboard widgets, palette providers, order/product/customer/settings panels, table columns/filters/bulk actions. This is where 90% of real project work happens.
3. Permissions — RBAC is the engine's. Permissions come from its ability catalog via ecommerce:sync-permissions, and shop-manager is the broad role. Confirm the role mapping before inviting real users.
4. The browser suite — Pest + Playwright covering main flows and accessibility; it doubles as documentation of intended behaviour.

First use case to validate the install end to end: create a product, place a test order through the engine's storefront, then work that order through the admin — status and sub-status, a shipment with tracking, a partial refund, and a note. That single path exercises authorization, the mutate rate limiter, the activity timeline, stock decrement against the default warehouse, and (if enabled) the Echo updates on the order screen.

Implementation Patterns

Extend through registries, don't fork screens. Register navigation sections and badge counts, dashboard widgets, table columns/filters/bulk actions, and the various panels rather than overriding Blade views. Registries plus filters are the sanctioned seam, and they survive engine upgrades far better than a published-view override.

Gate every custom surface with an engine ability. Custom nav items, widgets, bulk actions, and palette providers should declare the ability they need. The package authorizes its own screens against the engine's abilities; anything you add that skips that check becomes an authorization hole, and table bulk actions already skip records the user may not change — match that behaviour in your own actions.

Add your domain objects through the palette and pickers. If you have a custom entity users need to jump to (a supplier, a warehouse transfer, a return), a palette provider gives you Cmd+K for a few lines of registration. Same idea for pickers: reuse the picker registry for any "select a record" field so caching and capping behaviour is consistent.

Use panel extension points for domain data. Order panels are the right home for fulfilment integrations (3PL status, tracking sync); product type panels for custom product types; customer tabs for CRM data; settings tabs and config forms for per-store configuration. For the latter, read and validate against the engine's DescribesConfig schemas so your settings behave identically to core ones — don't bolt on hand-rolled validation.

Work the import pipeline rather than bulk-inserting. Catalog CSV import does column mapping, dry run, and queued resumable processing. The pattern that works: map columns once, always run the dry run in staging, then queue it in production and let the resumable job finish; schedule ecommerce-admin:prune-imports so error reports don't accumulate forever.

Wire webhooks as an operational tool, not just config. With a delivery log and replay, the normal loop is: endpoint breaks → fix your receiver → replay the failed deliveries from the admin instead of asking the merchant to re-trigger events. Same for notification templates — Twig with live preview, locales, and test sends means template changes can be validated in the UI and test-sent before going live.

Enable real time deliberately. Dashboard and order screens update over Laravel Echo when enabled. Turn it on for support/ops teams watching order flow; leave it off for low-traffic stores where the extra moving parts buy nothing.

Schedule price and promotion changes through the UI, not code. Per-currency scheduled prices and the promotion rule builder with plain-language summaries exist precisely so merchandising changes don't need a deploy. Hand those to the people who own the catalog.

Gotchas and Tips

Real-time silently off without GraphQL. rebing/graphql-laravel is now suggested, not required. If Echo updates never arrive, check that first, then broadcasting config — don't start debugging the Echo client.

Mutating Livewire updates hit the rate limiter. Anything that writes counts toward ecommerce.admin.mutate; polls, searches, sorting, and paging do not. Large bulk adjust / bulk action runs on a big selection can get throttled, so chunk big operations or raise the limiter for trusted admin roles. Conversely, heavy filtering and polling are cheap — don't over-optimise those.

Middleware runs on every Livewire update, not just page loads. Your configured admin middleware (2fa, verified) is applied per update. A user whose second factor lapses mid-session gets failures on save, which reads as a mysterious broken form. Always test with a 2FA-enabled, verified account, not your dev superuser.

Engine table prefix is handled — your code isn't. The package qualifies every column through its model so ecommerce_ prefixes work. Any custom column, filter, or join you add must do the same, or you'll get ambiguous/unknown column errors only on prefixed installs.

Bulk actions skip, they don't fail. Records the user may not change are silently skipped. Surface partial-success messaging in your own bulk actions (and check the package's) or users will assume everything applied.

License keys are matched by hash. Only a full key matches a search — partial or trailing-digit lookups return nothing. Don't build a support workflow around prefix search.

Refund arithmetic is opinionated. Refunds by amount are spread across order lines, and pending refunds reduce what's still refundable. "Refunded" only appears as an order status once the payment is actually refunded, so automations keyed on that status will lag the request. Test refund and restock flows after any engine bump.

Stock reads and writes use the engine's default warehouse. Multi-warehouse operations need the engine config, not an admin override.

The permission sync alias is deprecated. ecommerce-admin:sync-permissions still works but move deploy scripts and CI to ecommerce:sync-permissions now — permission drift after a deploy is an ugly, quiet failure mode.

CSP nonce required. Inline scripts carry the app's CSP nonce; a strict policy without nonce support will break charts and interactive screens in ways that look like JS bugs.

Selection, picker caches, and import error reports are capped. Don't assume "select all" means all — very large selections truncate. For mass changes, prefer the CSV bulk-adjust path.

The webhook secret is no longer in component public state. If you had tests or custom panels reading it off the Livewire component, they'll break; read it from the model/config side instead.

Extension-point hygiene: the unsaved-changes warning and the accessibility patterns (keyboard reordering with announcements, focus return, error summaries, table captions and sort state, live regions) are established conventions across screens. If you add a sortable list or custom panel, follow the same pattern — an axe check runs on every screen in the browser suite, so regressions surface in CI rather than in an audit.