Flux Erp Laravel Package

Getting Started

• Verify what you're actually installing first. flux-erp looks like a meta/ERP layer on top of flux-core; open composer.json in the repo and confirm whether it pulls flux-core plus modules, what Laravel/Livewire/PHP versions it constrains, and whether it expects a specific frontend stack (Vite + Alpine + Tailwind). That one file determines half your integration risk.
• Install into a throwaway Laravel app before touching a real codebase:

  composer require team-nifty-gmbh/flux-erp
  php artisan vendor:publish --provider="Flux\\..."   # confirm provider name via composer.json / src/
  php artisan migrate
  php artisan route:list --path=flux                   # or whatever prefix the provider registers
  

• Read these in order, before writing any code: src/*ServiceProvider.php (bindings, routes, Livewire registration, config merges), config/ (feature flags, table prefixes, auth guard), database/migrations/ (existing table names — this is where collisions bite), routes/, and any src/Contracts or src/Events directory. With 4 stars and likely thin docs, src/ is the documentation.
• First real use case: stand up the package's own UI if it ships one, then create one contact → one product → one order → one invoice end-to-end. That single flow exercises migrations, permissions/roles, currency/tax handling, and numbering sequences — the four things that are expensive to retrofit.
• Before customizing anything, run php artisan about, check config/app.php providers, and confirm whether the package registers a panel/route prefix and auth guard you must log into. Most "it renders blank" reports are an unseeded permission/role table or a guard mismatch.

Implementation Patterns

• Treat it as a modular monolith, not a library. Register your own service provider/module alongside it and extend through config, events, and published views. Keep a docs/upstream.md note of every place you deviate — you will need it at upgrade time.
• Extend models by composition first. If the package's Eloquent models aren't final, prefer: (a) relations + observers, (b) traits/concerns, (c) subclassing with a config-driven model map, and only last (d) forking. Check whether the provider resolves models via config('...models.contact') — if it does, swapping in your subclass is a one-line config change and is the cleanest hook available.
• Hook domain state changes via events, not overrides. Listen for order/invoice/stock events in your own provider, dispatch jobs from listeners, and keep the write path inside the package's services so numbering, tax, and audit trails stay intact.
• Money and documents: never store or compute currency as float. Find the package's money value object / cast and use it consistently in your own tables; ERP rounding bugs surface months later in tax reports.
• Permissions and roles: seed once, then wrap your own controllers/pages in policies that reference the package's permission names rather than hardcoding role IDs. Treat permission names as a public API you depend on.
• Custom data: if there's a settings/custom-field mechanism, use it instead of adding columns to upstream tables. Columns you add survive migrations fine — columns upstream adds do not survive your assumptions.
• Livewire integration: reuse the package's components where possible; publish and override views rather than copying components. Keep its JS/CSS build in your Vite config (or @fluxScripts-style directives) — a missing asset manifest is the most common "nothing works" failure.
• Data sync/API work: wrap multi-table writes (order + lines + stock movements) in DB::transaction(), queue external sync as jobs, and make them idempotent on the package's document/order identifiers.
• Testing: RefreshDatabase runs the package's migrations for you — good. Build factories for your models only, and assert against upstream factories where they exist rather than recreating fixtures.
• Versioning: pin an exact version or commit in composer.json. At this maturity, ^0.x will hand you breaking changes silently.

Gotchas and Tips

• Table-name collisions. If your app already has contacts, products, addresses, media, or orders, resolve this before the first migrate. Check for a configurable table prefix and decide early — renaming after data exists is painful.
• Permission/settings caches. Newly seeded permissions often don't appear until php artisan permission:cache-reset (or cache:clear). If a menu item or button is invisible, this is the first thing to check.
• config:cache hides your changes. Config merges from the provider are frozen into the cached config; remember to re-cache in deploy scripts after vendor:publish.
• Deletion order and FKs. ERP schemas are densely related. Soft deletes plus restrictive FKs mean "delete product" can fail on historical invoice lines — expect to deactivate/archive rather than delete, and build your UI around that.
• Numbering sequences and concurrency. Document numbers generated in PHP (max+1) rather than the DB will duplicate under load. Test with parallel requests before you trust invoices.
• Livewire/Alpine version drift. If the package pins Livewire 3 and your app is on 2 (or vice versa), install fails or components silently break. Resolve this at composer require time, not later.
• Debugging: php artisan route:list --path=<prefix>, Log::info() inside the package's service provider boot() (temporarily, via a local fork or dd()), and Laravel Telescope on a scratch install to see exactly which queries the UI fires. Telescope on a seeded demo DB is the fastest way to learn an undocumented ERP package.
• Extension points, ranked by safety: events/listeners → config → policies → published views → model-map config → subclassing → forking. Anything below "published views" needs a written upgrade plan.
• Bus factor is the real risk. 4 stars, 0 dependents, a single-vendor package: assume no community answers, no Stack Overflow, and slow or absent responses to issues. Budget for vendoring the source (repositories + path/VCS entry in composer.json) so you can patch a blocker on a Friday afternoon without waiting upstream. Keep your patches as a separate commit stack so rebasing on new releases stays tractable.
• Do a spike, then decide. Time-box an evaluation: install, seed, complete the order-to-invoice flow, and write one custom Livewire page against its models. If that spike takes more than a day or two, the day-to-day leverage probably isn't there yet — and that's the number that matters more than the feature list.