Nexopos Laravel Package

Getting Started

NexoPOS 6.2.4 is a Laravel application/package for retail POS, inventory, and procurement. Start by installing into a Laravel host with the documented installer, running migrations and seeders, and confirming the Modules/ directory is writable and registered.

First places to look:

• routes/ and Modules/*/Routes/ — most POS endpoints are module-scoped and now pass through hardened generic CRUD authorization.
• Modules/*/Resources/ (or resources/js/) — the Vue POS frontend, including the new unified layout controls and product-entry toolbar.
• config/ and module config files — POS layout defaults, price/permission settings, report branding.
• database/migrations/ — note the new procurement migration (default purchase units, scheduled reorder quantities) and run it before touching procurement UI.

First practical use case: stand up the POS, add a product with a purchase unit and reorder quantity, then exercise the products/cart/combined layout switch and the pinned-products popup. This validates the release’s headline features and the new validation/authorization paths in one pass.

Use the new category/product generation commands early to build a large enough catalog to test the searchable category selector and toolbar navigation under realistic volume.

Implementation Patterns

POS layout switching. Treat the unified POS layout control as a config-driven concern. Persist the preferred view (products, cart, combined) per user or per register rather than hardcoding it, so cashiers don’t re-select every session. Wrap the switch in a composable/store so pinned-product state and catalog navigation survive layout changes.

Pinned products. Pinned state belongs in the backend, not just local storage, if it must follow users across devices. Read the pinned-products popup as a read-heavy endpoint and cache it; validate pin/unpin through policies rather than trusting the client.

Product entry toolbar. The unified toolbar is the extension point for custom catalog workflows. If you add barcode entry, quick-create, or supplier lookup, hook into the toolbar’s action registry instead of forking the component. Keep toolbar actions permission-aware.

Catalog navigation at scale. With the searchable category selector, always send server-side search terms and pagination. Use debounce, abort in-flight requests on new keystrokes, and avoid loading the full category tree. For very large catalogs, precompute flat category paths for search.

Authorization. The release hardens generic CRUD authorization and read protection. Follow that pattern: define policies/abilities per resource, apply read protection at the route/controller level, and let the generic layer handle the rest. Don’t bypass it with direct model queries in custom controllers.

Server-side price and discount validation. POS price, wholesale price, product discount, and cart discount actions are now validated server-side. Mirror those rules in form requests and expose the same rules to the frontend via a shared validation endpoint or generated rules, so the UI fails fast and the server remains authoritative.

Temporary POS action permissions and polling. For actions like manual price override, model the grant as time-boxed (expiry, granted-by, scope) and rely on the permission polling behavior to refresh the UI. Keep the poll interval reasonable and pause polling when the tab is hidden.

Procurement. Populate default purchase unit and scheduled reorder quantity when creating products, then drive reorder suggestions from those fields. Treat them as defaults that can be overridden per supplier/product combination; don’t assume one unit system.

Reports. Use the report branding configuration rather than editing templates. Validate custom report layouts against the updated PDF layout compatibility before deploying; KPI rendering changes may affect custom blade/PDF partials.

Error handling. Frontend failures now surface server-provided messages via the snackbar with a localized fallback. Return meaningful message keys from Laravel validation/authorization exceptions, and add translations for any custom messages so the fallback isn’t the only thing users see.

Units. Unit management now exposes assigned-product counts — use this to warn before deleting or repurposing a unit, and to audit unit assignment during data imports.

Gotchas and Tips

• Run the upgrade migration before enabling procurement features. Existing installations will lack default purchase units and reorder quantities for current products; plan a backfill for high-turnover SKUs or reorder suggestions will be empty.
• Authorization hardening can surface as silent 403s. Generic CRUD read protection may block routes that previously worked. Audit custom controllers, API resources, and dashboard widgets, and check policies cover viewAny/view as well as writes.
• Server-side price validation breaks loose client flows. If your POS UI or API integrations send only the final price without the base price, discount type, or context, requests will now fail. Log the rejected payloads during rollout.
• Permission polling can mask or delay state. Temporary action permissions may appear granted after expiry until the next poll, or appear denied immediately after grant. Test with slow networks and confirm the grant’s server-side expiry is the source of truth.
• Queues no longer hang on failed API requests. That’s a fix, but it means failed product-unit and delivery operations now fail visibly. Make sure your retry/notification path handles terminal failures instead of assuming pending-forever.
• Searchable category selectors need indexing. Without a proper index on category name/path and a limit on result sets, the new selector can be slower than the old dropdown on large catalogs.
• Report branding and PDF layout changes can break custom templates. Re-generate or diff any customized report views; KPI rendering changes are the most likely regression point.
• Snackbar messages depend on your API contract. Standardize on a message field for 4xx/5xx responses; otherwise users only see the localized generic fallback, which makes support harder.
• Check version metadata and docs after upgrading. The release updates NexoPOS version metadata — verify composer.json/app version constants and any module compatibility checks that key off the version string.
• Use the new generation commands for test fixtures. Category and product generation commands with automated coverage are a fast way to reproduce large-catalog issues locally, but review generated data before pointing them at a staging database with real products.
• Extension points to prefer: policies for authorization, form requests for price/discount rules, toolbar/layout registries in the Vue POS, report branding config, and module service providers. Avoid patching core POS components directly so future releases remain upgradeable.