Laravel Crm Filament Laravel Package

Technical Evaluation

Architecture fit

• Unchanged in shape: this is a Filament UI layer over venturedrake/laravel-crm, not a standalone CRM. What changed is the coupling contract — v1.4.0 requires core ~2.5.0 (was ~2.4.2), so the panel no longer tracks core 2.4 patches at all. The compatibility gate flagged in the prior assessment has now closed in one direction: core 2.5.0 is required, and core 2.4.x is no longer served by this release line.
• The release is a deliberate alignment with core 2.5.0 rather than a feature grab. It removes ProductAttributeResource and its pages because core 2.5.0 deletes the ProductAttribute model the page was built on. Removing a UI that never had a backing table is the right call and reduces dead surface, but it is a host-visible removal, not an internal refactor.
• Product variations are the first panel feature that writes through core domain services (ProductService::syncVariations()). That is the correct direction — the panel stays a UI over core logic rather than a parallel persistence path — but it hardens the deploy-together requirement: variation data only persists correctly when core 2.5.0 is present.
• The panel also now re-implements a core behaviour: contact ↔ organization linking. Core performs this in its Livewire components rather than its services, so the panel's pages call PersonService::linkToOrganization() themselves across lead, deal, quote, order, invoice and purchase order. Functionally fine, but it is duplicated logic across six surfaces — if a later core release moves the call into a service, the panel has redundant code to unwind, and any panel page that misses the call produces inconsistent data.
• The purchaseOrderLines shim removal is a genuine simplification: the panel now submits the products shape core actually reads instead of maintaining a bespoke form-state contract.

Integration feasibility

• Feasible only for applications that can move to core 2.5.0. That is a substantive upgrade for the host: three migrations (variation columns, purchase-order line comments/order_product_id, removal of crm product attributes permissions), a deleted model, and a removed UI section.
• The upgrade is packaged as one command: php artisan laravelcrm:filament-update, which runs core's laravelcrm:update and therefore core 2.5.0's three migrations. A single documented entry point is a real adoption advantage over a manual migration list.
• Unlike v1.3.0, this release is not migration-free. Deploy pipelines that assumed "composer update only" must add an artisan step, with the associated backup and rollback planning.
• Hosts linking to filament.*.resources.product-attributes.* routes will 404 after upgrade. This is an inventory task, not a code task: search views, menus, dashboards, saved bookmarks and any custom navigation for those route names.
• The Filament asset fix implies a host-side prerequisite: composer hooks must actually run. Hosts that deploy with --no-scripts, or whose public/ is read-only, will not get the republished stylesheet and will keep the broken-table-scroll behaviour this release exists to fix.

Technical risk

• Version-mismatch risk is now asymmetric and severe. Panel 1.4.0 against core 2.4.x will fail Composer outright; panel 1.3.x against core 2.5.0 is unsupported and will hit the deleted ProductAttribute model and missing variation columns. There is no safe mixed state.
• Silent data risk on variation lines: the notes state variations only persist through core 2.5.0's services. A partial deploy — panel updated, migrations not run — risks variation edits that appear to save but do not persist correctly. This must be treated as a correctness risk, not a cosmetic one.
• Data-loss risk from the Product Attributes removal is low: the page never had a table, so there is no content to migrate. The permission rows for crm product attributes are deleted, however, and any role assignments referencing them need cleanup — cheap but easy to forget.
• Business-rule risk sits in variation pricing, not in code. Two rules need explicit sign-off: a variation without a price sells at the product price, and order → purchase order uses the variation's cost_per_unit before unit_price. The second is a margin-affecting default and should be validated by finance or product ops, not just engineering.
• A pre-existing data-integrity bug is fixed but may have already caused damage: for products priced only in a non-default currency, the edit form loaded blank and saving overwrote the price. Teams should check production for zeroed or clobbered prices on non-default-currency products, not just verify the fix.
• The quote → order conversion was throwing on crm_labelables.id. Any team that built a workaround around that failure should remove it.
• Carried forward unchanged from v1.3.0 and not addressed by this release: app-owned Xero dependency (dcblogdev/laravel-xero) with its silent sync-stop behaviour, Guzzle ^7 cap, PHP-side decrypted search when encrypt_db_fields is on, headless route gating, and the "empty select unlinks" relation-clearing semantics. Xero and encryption both need re-validation against the new core 2.5.0 baseline rather than assumed.

Key questions

• What are the supported PHP, Laravel and Filament version bounds for v1.4.0? The notes reference Filament v5 explicitly; confirm whether v4 is still supported.
• Are core 2.5.0's three migrations reversible? What is the documented rollback if laravelcrm:filament-update fails midway?
• Is laravelcrm:filament-update idempotent and safe to run on every deploy, or is it a one-shot upgrade command?
• What happens to existing crm product attributes permission rows and any role bindings to them — deleted cleanly, or left orphaned?
• For variation pricing: which price wins when a variation has no price in the document currency but the product does? Is that covered in tests?
• Is cost_per_unit before unit_price on order → purchase order conversion the intended default for all tenants, and is it configurable?
• Does Xero line-item sync understand variation SKUs and variation-level prices, or does it fall back to product-level data?
• Has the PersonService::linkToOrganization() call been verified on all six document types, and is it genuinely idempotent where a link already exists?
• What is the supported path for hosts whose deploy cannot write to public/ during composer install? Is running php artisan filament:assets in the build pipeline supported as an alternative?
• Is panel 1.3.x maintained as a branch for teams that cannot reach core 2.5.0, and for how long?
• Does the new variation select on line items introduce per-line queries on edit forms at realistic line counts?

Integration Approach

Stack fit

• Best fit: applications able to move to core 2.5.0 in the same release, on Filament v5, with working composer script hooks and a writable asset path at build time.
• Blocked fit: applications pinned to core 2.4.x. These should stay on panel 1.3.x and treat 1.4.0 as deferred, not pending.
• Needs remediation first: hosts with links into the product-attributes routes, hosts deploying with composer install --no-scripts, and hosts on read-only filesystems.
• Unchanged from v1.3.0: headless installs remain supported via LARAVEL_CRM_USER_INTERFACE=false; Xero users still own that dependency.

Migration path

1. Inventory the stack: core CRM version, panel version, PHP/Laravel/Filament versions, composer script configuration, asset write permissions, Xero usage, encrypt_db_fields, headless flag, and any multi-currency product pricing.
2. Decide the branch point: if core 2.5.0 is achievable now, proceed; if not, pin to panel ^1.3 and stop — do not attempt a partial upgrade.
3. Grep the host codebase for product-attributes route names and remove those links before or with the release.
4. Take a database backup. This is the first panel release in this line with migrations.
5. composer update venturedrake/laravel-crm venturedrake/laravel-crm-filament together — never one without the other.
6. Run php artisan laravelcrm:filament-update to apply core 2.5.0's three migrations. Confirm it completed before any application smoke test.
7. Clean up crm product attributes permission references in roles and any seeders.
8. Verify or repair the composer hook so laravelcrm:filament-upgrade runs filament:assets on post-autoload-dump; otherwise run php artisan filament:assets explicitly in the build pipeline.
9. Staging regression: variation CRUD, reorder, deactivate and remove on the product form; product view variations list; products index search by variation SKU; variation select on deal/quote/order/invoice/purchase-order lines including product-change clearing; conversions quote→order, order→invoice, order→purchase order with cost_per_unit behaviour; PDF, email and portal rendering of Product — Variation; purchase-order line edit persistence; product price load and save for a non-default-currency product; contact + organization saved together on all six document types; table horizontal scrolling under the current Filament version.
10. Audit production for prices previously blanked and overwritten by the non-default-currency bug.
11. If Xero is in scope, re-verify the integration against core 2.5.0: package present, Integrations page shows Connect, existing tokens and crm_xero_* rows intact, sync resuming without re-authorisation.
12. Deploy with migrations in a low-traffic window, then run cache/config clears and asset publishing, and smoke test.

Compatibility

• Core: ~2.5.0. Panel 1.4.0 does not support core 2.4.x. Panel 1.3.x is the last line compatible with core 2.4.2–2.4.7.
• Filament: v5 is referenced by the asset fix; confirm the exact supported range before assuming v4 hosts are covered.
• Xero: guidance unchanged (dcblogdev/laravel-xero:^1.1.3, Guzzle ^7) but unverified against core 2.5.0 — treat as a validation item this cycle.
• Encryption: unchanged — encrypt_db_fields on routes affected pickers through PHP-side decrypted matching rather than SQL LIKE.
• Headless: unchanged — LARAVEL_CRM_USER_INTERFACE=false must be set; Connect/Disconnect remain hidden.
• Routes: filament.*.resources.product-attributes.* no longer exist.
• Data model: ProductAttribute and its permissions are gone; variations are soft-deleted on removal so historical document lines retain their label.

Sequencing

• The two packages and the migration are a single atomic change. A panel-only deploy fails at dependency resolution; a core-only deploy leaves an unvalidated panel against a new core.
• Within the release: backup → composer update both → laravelcrm:filament-update → asset publish → cache clears → smoke test. Do not reorder the migration after the asset step.
• For Xero users, the Xero package must be present in the same release; the v1.3.0 warning about sync stopping silently still applies and now sits on top of a core minor upgrade.
• Teams planning core 2.5.x patch updates after this can expect the panel to track ~2.5.0 without a release, mirroring the previous 2.4 patch behaviour — but that should be confirmed rather than assumed, since v1.4.0 is the first release on this constraint.

Operational Impact

Maintenance

• Mixed. The panel is back to tight coupling with core minors: expect one panel release per core minor, and expect that release to carry migrations. The v1.3.0 "patch-tracking without panel releases" benefit still applies within 2.5.x, but the release boundary is now more expensive.
• Positive: meaningful dead code is gone — ProductAttributeResource, its pages, ProductVariationsRelationManager as a writable manager, and the purchaseOrderLines shim. Smaller surface, fewer places for form-state drift against core.
• Negative: the deploy path grew. The host now owns a migration step and an asset-publish step, and the panel ships a command that reaches into core's updater. That is convenient and also more to get wrong.
• The version matrix expands: core 2.5.x, panel 1.4.x, Filament version, Xero package, Guzzle, PHP/Laravel. Two of those columns are now hard-gated against each other.

Support

• Runbook additions: Product Attributes settings page is intentionally gone — direct users to product custom fields, and expect a spike in "missing menu item" and 404 tickets from bookmarks or custom nav.
• Variation semantics to document for support: removing a variation soft-deletes it and existing document lines keep their label; a variation with no price sells at the product price; line pickers and PDFs now render Product — Variation.
• Filament table scrollbar off-screen after an upgrade: check that filament:assets has run and that composer hooks are intact — this is the exact failure v1.4.0 fixes and it recurs wherever assets are stale.
• Contact and organization saved together are now automatically related; duplicates are not created. This is new user-visible behaviour and may generate "why are these linked?" questions.
• Purchase order line edits now save. If users had a workaround for edits not persisting, they should stop using it.
• Carried forward: the "clearing a contact or organization unlinks it" change from v1.3.0, the Xero silent-sync-stop diagnosis path, and the headless note that Connect/Disconnect are absent by design.

Scaling

• Variation lines add a child-table read and a conditional select on five document forms. The conditionality (only for products with active variations, or lines already on one) keeps the common case cheap, but edit forms loading each line's variation is a per-line lookup worth watching at high line counts.
• Products index search by variation SKU introduces a join or subquery on a table that grows with catalogue size. Measure on the largest catalogue before rollout.
• Everything from v1.3.0 still holds and is unaffected: server-side owner filters capped at 20 with search, bulk assign owner search, eager loading of emails, phones, next activity, default price, shipping address, Xero links and activity causers, and relation-clearing fixes.
• The encryption-on caveat is unchanged: PHP-side decrypted matching is correct but will not scale like SQL LIKE on very large contact/organization tables.

Failure modes

• Version mismatch: panel 1.4.0 with core 2.4.x fails Composer; panel 1.3.x with core 2.5.0 hits the deleted ProductAttribute model and absent variation columns.
• Migration not run: missing comments/order_product_id and variation columns produce save errors for purchase-order lines and variation edits that do not persist — the latter is the silent case to watch.
• Stale Filament stylesheet: table horizontal scrolling breaks with the scrollbar rendered off-screen, because filament:assets never ran. Most likely in --no-scripts deploys and read-only public/ filesystems, where composer install may also fail outright.
• Broken host links: any navigation or dashboard entry pointing at filament.*.resources.product-attributes.* now 404s.
• Custom code depending on the purchaseOrderLines form-state key breaks, since the shim is removed.
• Pre-existing corrupted prices: products priced only in a non-default currency may already have had their price blanked and overwritten before this fix. This is a latent data defect, not a forward-looking one.
• Permission cleanup skipped: orphaned references to crm product attributes in roles or seeders cause drift between environments.
• Xero: unchanged — missing dcblogdev/laravel-xero after a core upgrade stops sync with no exception and no failed job; tokens and rows are retained and sync resumes once installed.
• Relation clearing: "empty select unlinks" from v1.3.0 still applies and remains a behaviour change for existing user habits.

Ramp-up

• Medium for all adopters now, not just Xero/encryption/headless installs. This release carries schema changes, a removed UI surface, and a new feature with pricing semantics — none of which can be absorbed by a Composer bump alone.
• Add a finance or product-ops sign-off step for variation pricing defaults and the purchase-order cost_per_unit behaviour. This is the first release in this line where the risk is partly commercial rather than purely technical.
• TPM governance items: keep the core/panel compatibility gate explicit (panel 1.3.x for core 2.4, panel 1.4.x for core 2.5), own a migration and rollback policy for panel releases now that they carry schema change, assure composer hooks and asset publishing in CI rather than trusting host configuration, and retain ownership of the Xero dependency pending its re-validation on core 2.5.0.